Documentação
API de gerenciamento
Uma chave de gerenciamento permite que seus próprios sistemas criem, agrupem, limitem e revoguem as chaves de API da sua conta e leiam quanto elas gastaram, pela API. Ela não pode chamar um modelo.
Para que serve
Algumas integrações dão a cada cliente, equipe ou usuário uma chave de API própria, colocam as chaves de cada cliente em um grupo, definem um teto de gasto por grupo e leem o custo por chave ou por grupo. Na página Chaves de API isso funciona bem para poucas chaves. Para mais, uma chave de gerenciamento permite que um script ou sua própria ferramenta de administração faça o mesmo pela API.
Uma chave de gerenciamento é uma credencial diferente de uma chave de API. Ela não é aceita onde uma chave de API é aceita: não pode chamar /v1/chat/completions, /v1/messages nem qualquer outra rota de modelo. Ela funciona apenas em /v1/management/, e ali uma chave de API não funciona.
Crie uma chave de gerenciamento
- Abra a página Chaves de API e vá até o final. Em “Chaves de gerenciamento”, escolha “Nova chave de gerenciamento”. O bloco fica recolhido até você abri-lo.
- Dê um nome à chave, por exemplo sincronização de cobrança, para que a página possa dizer qual programa fez cada alteração.
- Informe os endereços de onde ela pode ser chamada, um por linha: um único endereço como 203.0.113.7 ou um intervalo como 203.0.113.0/24. Sem uma lista de permitidos, qualquer pessoa com a chave pode usá-la, e a janela avisa se você deixar a lista vazia.
- Copie a chave quando ela for exibida. Ela é exibida uma única vez: a Kunavo guarda apenas um hash dela.
Uma conta pode ter duas chaves de gerenciamento ativas ao mesmo tempo. Revogue uma para abrir espaço para outra.
Chame a API
Envie a chave como token Bearer para https://api.kunavo.com/v1/management. Chaves de gerenciamento não são aceitas a partir de um navegador: as respostas não trazem cabeçalhos CORS, então uma página de outro site não pode chamá-las. Uma chave deve ficar no seu servidor, nunca em código de front-end.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"As respostas são JSON. Os erros têm o mesmo formato do restante da API: um objeto error com um message, um type, um code e, quando se aplica, o param incorreto. Estes são os status que você vai encontrar:
| Status | O que significa |
|---|---|
401 | A chave está ausente, digitada errado ou revogada, ou a conta dela está suspensa ou em análise. |
403 | A chave tem uma lista de IPs permitidos e a solicitação veio de um endereço que não está nela. |
404 | O grupo ou a chave não existe, foi excluído ou pertence a outra conta. Os três casos respondem da mesma forma, então um id de outra conta não revela nada. |
409 | A alteração entra em conflito com o estado da conta: um nome de grupo já em uso, uma chave revogada ou a conta no limite de 500 chaves ativas. |
429 | Esta chave fez 60 solicitações no último minuto. O cabeçalho Retry-After informa quantos segundos esperar. |
Grupos
GET /v1/management/groups lista os grupos da conta, com o limite mensal de cada um e quantas chaves ativas ele contém. POST cria um, com um monthly_limit_usd opcional; um nome já em uso retorna 409. PATCH /v1/management/groups/{id} altera o nome ou o limite: envie null para não ter limite e 0 para pausar todas as chaves do grupo sem revogar nenhuma. DELETE remove um grupo, e as chamadas dele mantêm o nome na página Uso. As chaves dele continuam ativas e ficam sem grupo, a menos que você adicione ?revoke_keys=true, que também as revoga.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001", "monthly_limit_usd": 50}'Chaves
GET /v1/management/keys lista as chaves, da mais recente para a mais antiga. Uma página tem 50 chaves, e limit aumenta isso para 100. status é active por padrão, ou revoked ou all, e group_id restringe a lista a um grupo. Quando has_more é true, passe next_after como after para ler a página seguinte. O texto puro de uma chave nunca é listado.
POST /v1/management/keys cria uma chave com um nome e, opcionalmente, um group_id, um monthly_limit_usd e um ip_allowlist. A resposta traz o texto puro no campo key, uma única vez. Um POST repetido cria uma segunda chave, então, antes de tentar de novo, liste as chaves e procure o nome dela.
curl https://api.kunavo.com/v1/management/keys \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'PATCH /v1/management/keys/{id} altera o nome, o grupo, o limite ou a lista de permitidos de uma chave; um group_id igual a null a tira do grupo. DELETE a revoga. Revogar uma chave que já está revogada não é um erro. Uma chave revogada não pode ser alterada.
curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Uso
GET /v1/management/usage informa o uso de toda a conta em até 90 dias UTC, assim como GET /v1/usage informa o de uma chave. group_by aceita qualquer combinação de group, api_key, model e day, e o padrão é api_key. Os números significam o mesmo que na página Uso: uma chamada conta no grupo em que a chave estava quando ela foi feita, uma chamada com falha não custa nada, e o total de um período é igual, ao centavo, à exportação CSV dos mesmos dias. group_id e api_key_id restringem o relatório a um grupo ou a uma chave.
curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"end_date posterior a hoje é lido como hoje, e a resposta devolve a data final que usou.Mantenha-a segura
- Defina uma lista de permitidos. Uma chave que só funciona a partir dos endereços do seu servidor vale pouco para quem a roubar.
- Guarde a chave em um cofre de segredos no servidor que executa sua ferramenta. Nunca a coloque em um navegador, em um aplicativo móvel ou em um repositório.
- Se ela vazar, revogue-a no final da página Chaves de API ou com
DELETEnela. A janela de revogação também pode revogar as chaves que essa chave criou. - Cada alteração que a chave faz pela API aparece em “Chaves de gerenciamento” na página Chaves de API, com o horário, o endereço de origem e a chave que a fez: as últimas 50 alterações. As alterações feitas manualmente nessa página não são listadas.
- Uma chave deixa de funcionar por conta própria quando a conta dela é suspensa ou colocada em análise, e quando é revogada.
Uma chave de gerenciamento pode fazer 60 solicitações por minuto. Faça uma solicitação por alteração e leia uma lista em páginas, em vez de chave por chave.
Relacionado
Os grupos, seus limites mensais e a forma como seus números são contados estão explicados na página de grupos de chaves. Os números de uso são os mesmos da página Uso.