Mecanismo de autenticação
A API Cyrus usa API Keys para autenticar todas as requisições. As chaves devem ser enviadas no header HTTP X-API-Key.
Requisições sem autenticação ou com chave inválida retornam 401 Unauthorized:
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "API Key inválida ou ausente"
}
}Tipos de chave
Chaves de produção (sk_live_)
Utilizadas em produção. Cada operação realizada com estas chaves é real — cobranças geram QR Codes válidos, pagamentos movimentam saldo real.
Chaves sandbox (sk_sandbox_)
Utilizadas para testes. Comportamento idêntico ao de produção, mas sem movimentação financeira real. Veja Ambientes para detalhes.
Escopo das chaves
Todas as chaves têm acesso ao conjunto completo de endpoints /v1/*. Não há escopos granulares por endpoint — gerencie o acesso controlando quais chaves você distribui.
Ciclo de vida das chaves
As chaves são permanentes — não expiram automaticamente. Boas práticas:
- Rotacione periodicamente (recomendado a cada 90 dias)
- Revogue imediatamente se suspeitar de vazamento
- Use uma chave por integração para facilitar rastreamento e revogação
- Nunca reutilize chaves entre ambientes distintos
Autenticação do painel admin
O painel administrativo Cyrus usa autenticação por JWT, gerenciada internamente via /admin/auth/login. Isso é separado das API Keys e não é necessário para integrações de terceiros.
Próximos passos
- Gerenciar API Keys — criar, listar e revogar chaves
- Rate Limits — limites de requisição por chave