API keys com escopo, rate limit separado por método.
Cada key com permissões granulares. Limites distintos para GET (read) e mutation (POST/PUT/PATCH/DELETE). Revogação imediata. Last used trackeado.
Sistema
Hash
armazenamento (key nunca visível após criação)
200/min
GET default
60/min
mutation default
Por org
rate limits customizáveis
ApiKey — recursos
Escopo de Permissões
API key herda subset das permissões da organização. Read-only vs write controlado por scope.
- Mesmo padrão de strings que dashboard (billing.*)
- Restrição por recurso (apenas invoices, apenas customers, etc)
- Auditoria via AuditLog
Rate Limit Separado
RateLimitConfig por organização. GET e mutation com limites diferentes.
- getRequestsPerMinute (default 200)
- getRequestsPerHour (default 5.000)
- mutateRequestsPerMinute (default 60)
- mutateRequestsPerHour (default 1.000)
- 429 com header Retry-After
Revogação Imediata
Mark revokedAt. Próxima requisição com a key retorna 401.
- revokedAt set
- 401 imediato
- Sem propagação
Last Used Tracking
Cada chamada atualiza lastUsedAt. Útil para identificar keys inativas e fazer cleanup.
- lastUsedAt em cada chamada
- Cleanup de inativos
- Tracking contínuo
Criação Auditada
AuditLog registra criação e revogação com userEmail/userExternalId. Visível em /sistema/auditoria/.
- AuditLog completo
- userEmail + userExternalId
- Auditoria garantida
Multi-ambiente
Keys distintas para production, staging, sandbox. Cada ambiente com base URL própria.
- production / staging / sandbox
- Base URL própria
- Keys isoladas
Key Nunca Re-exibida
Key real só visível 1× no momento da criação. Hash SHA-256 armazenado. Perdeu? Crie nova e revogue a antiga.
- Visível 1× na criação
- Hash SHA-256 armazenado
- Rotação obrigatória se perdida
Prefix para Identificação
8 chars visíveis (ex: sk_live_abc1). Permite identificar a key em logs sem expor o secret completo.
- 8 chars visíveis
- Identificação em logs
- Secret protegido
Criar API key
bash
curl -X POST https://api.billing.kobana.com.br/v1/api-keys \
-H "Authorization: Bearer sk_admin_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Backend Produção",
"permissions": [
"billing.api.invoices.list",
"billing.api.invoices.show",
"billing.api.subscriptions.create"
]
}'response
{
"id": "ak_xyz",
"name": "Backend Produção",
"prefix": "sk_live_",
"key": "sk_live_abc123def456...",
"permissions_count": 3
}