This page is not yet available in English. Read it in Portuguese

Skip to content

Chaves de API e escopos: o mínimo para cada tarefa

Equipe AIUBYEngenharia de plataforma

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.

bash
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 deEscopoProduto que tem de estar ativo
Chamar modelos (chat, no formato da OpenAI ou da Anthropic)gateway:invokeModels
Buscar nos documentos do workspaceknowledge:readKnowledge
Enviar documentos para as bases do workspaceknowledge:writeKnowledge
Iniciar um agente publicado e ler as próprias execuçõesagents:runAgents
Executar um prompt publicado da bibliotecaprompts:runAgents
Iniciar um fluxo publicado com gatilho por APIflows:runAgents
Exportar a auditoriaaudit:readGuard
Ler aplicações e planos do Compute (CLI)compute:readCompute
Cadastrar aplicações e revisões (CLI)compute:writeCompute
Implantar e parar aplicações (CLI)compute:deployCompute
Pedir o token de acesso de uma aplicação com endereço protegidocompute:invokeCompute

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. O compute:deploy fica 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:

bash
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çãoHTTPMensagem ou código
Token ausente, errado, vencido ou revogado401Credencial ausente ou inválida.
A chave não tem o escopo da rota403A credencial não tem o escopo knowledge:read.
A rota só aceita pessoa logada, não chave401Esta rota exige uma sessão de usuário.
A organização não tem o produto, ou ele foi suspenso404Não encontrado.
A organização não tem conta de faturamento402billing_account_required
Mensalidade de produto sem pagamento além do prazo402subscription_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:

json
{
  "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:read só 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:decide e guard:perimeter existem, 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.