Chaves de API e escopos: o mínimo para cada tarefa
Chaves de API + escopos + respostas da API
Uma chave de API da AIUBY não é uma senha da organização: é uma permissão recortada, presa a um workspace e a uma lista de escopos. Este texto mostra qual escopo cada tipo de integração precisa, e o que a API devolve, com o código e a mensagem exatos, quando falta alguma coisa. A referência completa está em Chaves de API, na documentação.
#O que uma chave carrega
- Um workspace. Escolhido na criação. O corpo da requisição não muda isso: organização e workspace saem sempre da chave.
- Uma lista de escopos. Cada rota exige um escopo. Sem ele, a chave não entra.
- Uma validade. 90 dias por padrão, 365 no máximo.
- Um nome. Tudo o que a chave faz fica na auditoria com esse nome.
O token começa com aiuby_ e aparece uma única vez, na criação. Vai no cabeçalho de autorização; o Gateway de modelos aceita também x-api-key.
export AIUBY_TOKEN="aiuby_..."#O escopo de cada tarefa
A regra é dar a cada sistema uma chave própria, com o menor conjunto de escopos que resolve.
| O sistema precisa de | Escopo | Produto que tem de estar ativo |
|---|---|---|
| Chamar modelos (chat, no formato da OpenAI ou da Anthropic) | gateway:invoke | Models |
| Buscar nos documentos do workspace | knowledge:read | Knowledge |
| Enviar documentos para as bases do workspace | knowledge:write | Knowledge |
| Iniciar um agente publicado e ler as próprias execuções | agents:run | Agents |
| Executar um prompt publicado da biblioteca | prompts:run | Agents |
| Iniciar um fluxo publicado com gatilho por API | flows:run | Agents |
| Exportar a auditoria | audit:read | Guard |
| Ler aplicações e planos do Compute (CLI) | compute:read | Compute |
| Cadastrar aplicações e revisões (CLI) | compute:write | Compute |
| Implantar e parar aplicações (CLI) | compute:deploy | Compute |
| Pedir o token de acesso de uma aplicação com endereço protegido | compute:invoke | Compute |
Um escopo só aparece para escolha se o produto dele estiver ativo na organização. Três exemplos do que isso dá na prática:
- Um site que só responde dúvidas com a base de conhecimento precisa de
knowledge:read, e de mais nada. - Um pipeline que só confere se a configuração pode ser implantada usa
compute:read. Ocompute:deployfica numa chave separada, usada só na etapa de publicação. - Um ERP que dispara um fluxo de aprovação usa
flows:run. Ele consulta apenas as execuções que a própria chave iniciou.
Uma busca no Knowledge, por exemplo:
curl -sS -X POST "https://aiuby.com/api/platform/knowledge/search" \
-H "Authorization: Bearer $AIUBY_TOKEN" -H "Content-Type: application/json" \
-d '{"query":"prazo de devolução","limit":5}'#O que a API responde quando algo falta
As conferências acontecem a cada requisição, nesta ordem: a chave, o escopo, o produto e a conta de faturamento. Uma chave criada com tudo certo deixa de funcionar no momento em que uma dessas coisas muda.
| Situação | HTTP | Mensagem ou código |
|---|---|---|
| Token ausente, errado, vencido ou revogado | 401 | Credencial ausente ou inválida. |
| A chave não tem o escopo da rota | 403 | A credencial não tem o escopo knowledge:read. |
| A rota só aceita pessoa logada, não chave | 401 | Esta rota exige uma sessão de usuário. |
| A organização não tem o produto, ou ele foi suspenso | 404 | Não encontrado. |
| A organização não tem conta de faturamento | 402 | billing_account_required |
| Mensalidade de produto sem pagamento além do prazo | 402 | subscription_suspended |
O 404 para produto ausente é de propósito: a resposta é igual à de uma rota que não existe, então uma chave não serve para descobrir o que a organização contratou.
No Gateway de modelos os erros vêm sempre com código:
{
"error": {
"code": "forbidden",
"message": "A credencial não tem o escopo gateway:invoke."
}
}403 product_not_active: a organização não tem o Models ativo. Uma chave antiga para de chamar modelos se o Models for suspenso ou removido.402 insufficient_credit: a conta existe, mas o saldo pré-pago acabou. É diferente de não ter conta.
A lista completa de códigos do Gateway está em Erros, na documentação.
#A chave nunca pode mais do que quem a criou
- Quem cria chave é o dono ou um administrador.
audit:readsó pode ser dado por quem administra a organização inteira. Um administrador de um workspace não exporta a auditoria pela tela, então a chave que ele cria também não exporta.- Quando a pessoa que criou a chave é removida da organização ou perde o papel de administração, as chaves que ela criou e não administra mais são revogadas na mesma operação.
- Encerrar a organização revoga todas as chaves na hora.
#Trocar sem parar o sistema
Trocar o token não exige janela de manutenção: ao trocar, o token anterior pode continuar valendo por até 24 horas. A ordem que funciona:
- Troque a chave na tela e guarde o token novo no cofre de segredos.
- Atualize os sistemas, um por vez, enquanto o antigo ainda responde.
- Confira na auditoria que as chamadas já chegam pelo token novo.
- Se o motivo da troca foi vazamento, não espere: revogue. A revogação é imediata.
#Limites
Limite
Cada workspace pode ter até 20 chaves ativas. Não existe chave que valha para a organização inteira nem para mais de um workspace, e o token não pode ser lido de novo depois da criação.
- Criar, trocar e revogar chave é só pela tela. Não há rota para uma chave criar outra.
- Adicionar produto, mudar orçamento e liberar modelo também não aceitam chave: exigem uma pessoa logada.
guard:decideeguard:perimeterexistem, mas são de uso exclusivo da extensão e do proxy do Guard.
Para a primeira chamada de modelo do começo ao fim, siga Sua primeira chamada à API de chat da AIUBY.



