Primeiros passos

Autenticação

Toda requisição é autenticada com a sua chave secreta, enviada como token Bearer sobre HTTPS. Esta página mostra o cabeçalho, os dois tipos de chave e os erros que você recebe quando algo está errado.

Nesta página

Autenticação Bearer

Envie a sua chave secreta no cabeçalho Authorization com o esquema Bearer. Não existe chamada de login, sessão ou troca de token: a chave identifica a sua conta em cada requisição.

Cabeçalho AuthorizationHTTP

Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b

As requisições precisam usar HTTPS. Chamadas em HTTP simples não são aceitas.
A chave vai só no cabeçalho, nunca na URL nem no corpo, para não parar em logs ou no histórico do navegador.
Chaves de teste só alcançam dados de teste, os únicos que existem hoje. Quando chegarem as chaves de produção, cada tipo de chave vai ficar no próprio ambiente.

Uma requisição autenticada

curl https://api.krokopay.app/v1/charges/chg_4Fp9KzW1xQm7Rt \  -H "Authorization: Bearer $KROKOPAY_SECRET_KEY"

Chave publicável e chave secreta

A sua conta tem duas chaves de teste. Elas não são intercambiáveis:

Chave	Prefixo	Onde fica	O que pode fazer
Secreta	`kp_test_sk_`	Só no seu servidor	Todos os endpoints desta documentação
Publicável	`kp_test_pk_`	Pode ir numa página web	Nada por enquanto: reservada para uso futuro no navegador

Todos os endpoints documentados exigem a chave secreta. Os dados de pagamento são coletados pelo checkout hospedado, então o seu front-end nunca precisa de chave para receber um pagamento. A chave publicável existe para que um recurso futuro no navegador possa chegar sem mudar a sua configuração de chaves; quais endpoints ela vai liberar ainda será anunciado.

Atenção: Nunca envie a chave secreta para um navegador ou app

Quem lê a chave secreta consegue criar cobranças e reembolsos na sua conta. Mantenha-a no servidor e troque-a na hora se ela vazar (veja Chaves de API).

Erros de autenticação

Problemas de autenticação vêm no objeto de erro de sempre. Não tente de novo: a mesma requisição vai falhar do mesmo jeito até a chave ser corrigida.

Status	`type`	`code`	Causa
`401`	`authentication_error`	`missing_api_key`	Sem cabeçalho `Authorization`, ou fora do formato `Bearer <chave>`.
`401`	`authentication_error`	`invalid_api_key`	A chave está malformada, é desconhecida ou foi substituída numa troca.
`403`	`permission_error`	`secret_key_required`	Uma chave publicável foi usada num endpoint que exige a chave secreta.

Chave ausenteHTTP

HTTP/1.1 401 UnauthorizedContent-Type: application/json{  "error": {    "type": "authentication_error",    "code": "missing_api_key",    "message": "No API key provided. Send it as `Authorization: Bearer <secret key>`."  }}

Chave inválidaHTTP

HTTP/1.1 401 UnauthorizedContent-Type: application/json{  "error": {    "type": "authentication_error",    "code": "invalid_api_key",    "message": "The API key provided is not valid."  }}

Chave publicável usadaHTTP

HTTP/1.1 403 ForbiddenContent-Type: application/json{  "error": {    "type": "permission_error",    "code": "secret_key_required",    "message": "This endpoint requires a secret key (kp_test_sk_…). Publishable keys cannot call it."  }}

Boas práticas

Leia a chave de uma variável de ambiente, como KROKOPAY_SECRET_KEY, nunca do código-fonte.
Monte o cabeçalho Authorization num único lugar do código, para que a troca da chave seja mudar uma variável.
Trate um 401 no código de produção como alerta para o seu time, não como erro para o usuário.
Nunca registre os cabeçalhos completos nos logs. Se precisar identificar uma chave, guarde só o prefixo.