API Keys

Em /dashboard/api a organização gerencia as chaves de API. Cada chave pertence a uma organização, tem um conjunto de escopos e pode ser revogada a qualquer momento.

:::caution A API pública não usa mais chave de API A /api/v1 passou a aceitar apenas o access token do Authorization Server da Kobana (Authorization: Bearer <token>), verificado contra a chave pública que ele publica. Uma chave criada aqui não autentica a API pública.

O motivo é que a chave era ao mesmo tempo a credencial e o que a verificava: quem lesse o repositório de chaves agia como qualquer organização, e cada rotação era uma conversa com um cliente. Com o token, quem emite é o Authorization Server e a plataforma só consegue verificar. :::

Tipos de chave

• Live (sk_live_...) — usadas em produção. Operam contra dados reais e geram cobranças reais.
• Test (sk_test_...) — apontam para o sandbox; ideal para integração inicial e testes automatizados.

Criar uma chave

1. Clicar em Nova chave.
2. Dar um nome descritivo (ex.: "Backend produção", "Worker de importação").
3. Selecionar os escopos:
   • subscriptions:read / subscriptions:write
   • invoices:read / invoices:write
   • payments:read / payments:write
   • customers:read / customers:write
   • nfes:read / nfes:write
   • webhooks:manage
4. Opcionalmente restringir por IP (lista de prefixos CIDR).
5. A chave é exibida uma única vez após criada. Copiar e guardar em cofre.

Boas práticas

• Uma chave por aplicação — facilita revogar acesso sem impactar outros sistemas.
• Escopos mínimos — conceder apenas o que a aplicação precisa.
• Rotação periódica — gerar nova chave, atualizar a aplicação e revogar a antiga.
• Nunca commitar — chaves devem viver em variáveis de ambiente ou cofre de segredos.

Rate limits

Cada chave respeita os limites configurados em Rate Limiting. Excedentes retornam 429 Too Many Requests com header Retry-After.

Auditoria e uso

A página mostra:

• Status — active ou revoked
• Último uso — data, IP e endpoint chamado
• Volume — requisições nas últimas 24h e nos últimos 30 dias

Toda criação ou revogação é registrada em Auditoria.

Documentação da API

A referência completa dos endpoints está disponível na seção API do menu lateral.

Captura de tela