Chaves de API
Criar, rotacionar e proteger as chaves ky_XXXXX-XXXXX-XXXXX, de teste e de produção.
A integração servidor-a-servidor usa chave de API nas rotas publicadas para esse modo de autenticação. A chave pode ter escopos, data de expiração e pode ser revogada.
Header
X-API-Key: ky_XXXXX-XXXXX-XXXXXFormato e ambiente
A chave tem o formato ky_XXXXX-XXXXX-XXXXX: três grupos de cinco letras maiúsculas e números. O ambiente não está na string. Ele é definido quando você cria a chave e aparece como rótulo na lista de chaves:
| Ambiente | Movimenta dinheiro real |
|---|---|
| Teste | Não. Opera num sandbox isolado, com provedor simulado. Ver Sandbox e produção. |
| Produção | Sim |
Cobranças reais só funcionam depois do cadastro aprovado.
Nota
Chaves antigas, no formato kyvo_live_… e kyvo_test_…, continuam válidas. As antigas de teste também passam a operar no sandbox.
Criar
Abra Integrações → Chaves de API
No painel da conta.
Escolha o ambiente e o nome
Use um nome que diga onde a chave roda:
checkout-prod,worker-conciliacao,staging. Uma chave por sistema facilita revogar sem derrubar o resto.Copie o segredo na hora
O valor completo aparece uma única vez. Depois disso só dá para ver o prefixo.
Onde guardar
- Variável de ambiente ou cofre de segredos.
- Nunca no front-end, em app mobile, em repositório ou em imagem de container pública.
- Nunca em chamado de suporte, print ou mensagem. Ninguém da KyvoPay vai pedir sua chave.
Segurança
Se uma chave vazou, revogue primeiro e investigue depois. Revogar não afeta as outras chaves da conta. A borda guarda a chave em cache por cerca de 60 segundos, então uma chave revogada pode continuar sendo aceita por esse intervalo — leve esse tempo em conta ao avaliar o que foi exposto.
Rotacionar sem downtime
Crie a chave nova
A conta aceita mais de uma chave ativa ao mesmo tempo.
Publique com a chave nova
Troque a variável de ambiente e faça o deploy.
Confirme que nada usa a antiga
Acompanhe o uso pelo painel.
Revogue a antiga
Depois que o tráfego zerar.
Erros comuns
| Status | O que costuma ser |
|---|---|
401 | Chave ausente, com espaço sobrando, revogada ou do outro ambiente |
403 | Chave válida, mas sem permissão para essa rota, ou chamada vinda de um IP fora da lista permitida da chave |