API

Chaves de API do ArchibotChat

Crie, copie, rotacione e revogue chaves de API geradas e conecte uma ferramenta de colaborador externo ao endpoint público do Archibot.

Administradores de clientesMembros do clienteOperadores da plataforma

Última atualização 18 de junho de 2026

As chaves de API permitem chamar o endpoint público do Archibot a partir de scripts, ferramentas de agente local e integrações que rodam fora de um workspace gerenciado. Elas são separadas da credencial oculta que alimenta a tela de Chat do navegador, que nunca é mostrada aos usuários.

Os workspaces gerenciados do Archibot já provisionam suas próprias chaves automaticamente. Use uma chave de API gerada apenas para uma ferramenta de agente local, uma extensão de editor ou um harness de propriedade do cliente que deva chamar o Archibot como colaborador externo.

Quando usar chaves de API

Crie uma chave gerada quando você precisar:

• Chamar o Archibot a partir de um script ou tarefa agendada.
• Conectar uma ferramenta de agente local ou extensão de editor ao endpoint.
• Executar um cliente compatível com OpenAI contra o endpoint do Archibot.
• Conectar um harness de propriedade do cliente fora do workspace ao Archibot.

Para perguntas interativas, use a tela de Chat do navegador. Consulte Usando o ArchibotChat.

Abrir a aba Chaves de API

1. Abra Configurações na navegação à esquerda.
2. Selecione a visualização Archibot account.
3. Abra a aba API Keys.

A aba fica na mesma linha que Setup, Git access, CI & Review, Support, Activity e Billing. Se o acesso à API não estiver habilitado para a conta, a aba mostra a mensagem API access is not enabled for this account. e o botão Create key fica desabilitado. Peça primeiro a um administrador do cliente ou à ISM para habilitar o portão de produto da API. Consulte Configuração do ArchibotChat.

Criar uma chave

1. Na aba API Keys, escolha Create key.
2. A nova chave aparece no topo da lista, e seu valor completo é mostrado uma única vez em um aviso destacado que diz Copy this key now. It will not be shown again.
3. Escolha Copy ao lado do valor da chave.
4. Armazene-a no seu gerenciador de segredos aprovado ou ambiente de execução.

As chaves são nomeadas automaticamente (por exemplo, Console generated key 1) e recebem o escopo api. O valor bruto é mostrado apenas neste aviso. Depois que você sai da aba ou cria outra chave, somente o prefixo da chave e os metadados permanecem visíveis.

Se o botão de copiar não conseguir acessar sua área de transferência, a aba mostra Clipboard copy unavailable. Selecione o texto da chave manualmente e copie-o antes de navegar para outro lugar.

Conectar uma ferramenta de colaborador externo

O cartão External coworker access cria um script de configuração pronto para executar, para que você não precise montar as variáveis de ambiente manualmente.

O cartão mostra dois campos de referência:

Abaixo desses campos, uma prévia mostra um script de shell que exporta as variáveis de ambiente do endpoint e da chave e executa um comando de colaborador de exemplo. Quando você acabou de criar ou rotacionar uma chave, o script inclui esse valor de chave de uso único; caso contrário, ele usa um espaço reservado <new-api-key>.

1. Crie ou rotacione uma chave para que o campo Key source mostre New one-time key included.
2. Escolha Copy setup no cartão External coworker access.
3. Cole o script no seu shell local, gerenciador de segredos ou configuração da ferramenta.

O script define variáveis padrão compatíveis com OpenAI (OPENAI_BASE_URL, OPENAI_API_KEY) junto com variáveis de colaborador do Archibot, para que tanto os clientes compatíveis com OpenAI quanto o ferramental de colaborador do Archibot usem o mesmo endpoint e a mesma chave. Use a URL do endpoint de produção fornecida pela ISM para sua conta, em vez de inferi-la de um exemplo local.

Usar uma chave

Use a chave como token bearer contra o endpoint compatível com OpenAI do Archibot.

curl https://chat.example.archibot.cloud/v1/responses \
  -H "Authorization: Bearer $ARCHIBOT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "archibot",
    "input": "Summarize this Archibus request queue export."
  }'

O endpoint encaminha campos da API de Responses compatíveis com OpenAI, como tools, tool_choice, reasoning, metadata e conteúdo input estruturado, para o endpoint do Archibot depois que as verificações de chave de API e de créditos passam.

Para respostas transmitidas, envie stream: true:

curl -N https://chat.example.archibot.cloud/v1/responses \
  -H "Authorization: Bearer $ARCHIBOT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "archibot",
    "input": "Draft a short work plan for this Archibus data cleanup.",
    "stream": true
  }'

As respostas transmitidas retornam evidências de cobrança em cabeçalhos de resposta X-Archibot-* em vez de reescrever cada fragmento de evento.

A descoberta de modelos compatível com OpenAI usa a mesma chave bearer:

curl https://chat.example.archibot.cloud/v1/models \
  -H "Authorization: Bearer $ARCHIBOT_API_KEY"

A descoberta de modelos não consome sua cota de uso.

Limites de taxa

As chaves de API geradas têm um limite de requisições por chave. As respostas incluem os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Quando o limite é excedido, o endpoint retorna 429 com um cabeçalho Retry-After.

Expiração

As chaves de API geradas expiram um ano após a criação. Cada linha de chave mostra suas datas de criação, expiração e último uso ao lado do prefixo da chave.

As chaves expiradas permanecem visíveis por nome, prefixo e metadados para que você possa auditar integrações antigas, mas elas não podem mais chamar a descoberta de modelos nem o endpoint de respostas. As rejeições de chave expirada acontecem antes de qualquer uso ser contabilizado. Rotacione uma chave expirada para emitir uma substituta sob o mesmo nome e escopo, ou revogue-a se a integração for descontinuada.

Rotacionar uma chave

Rotacione uma chave quando uma integração deve continuar funcionando sob o mesmo nome e escopo, mas o valor secreto precisa mudar.

1. Na aba API Keys, encontre a chave ativa por nome ou prefixo.
2. Escolha Rotate naquela linha de chave.
3. Copie o valor substituto do aviso de uso único.
4. Atualize o script, a entrada do gerenciador de segredos ou o ambiente de execução afetado.

A rotação revoga a chave anterior e cria uma substituta com o mesmo nome e escopo. O valor substituto é mostrado apenas uma vez, no mesmo aviso usado para chaves novas. A rotação age imediatamente; não há um diálogo de confirmação separado, então esteja pronto para atualizar a integração antes que o tráfego antigo falhe.

Revogar uma chave

Revogue uma chave quando:

• Ela não é mais usada.
• Ela foi colada em um chat, e-mail, ticket, repositório ou documento compartilhado.
• O proprietário sai da equipe.
• A integração é substituída.

1. Na aba API Keys, encontre a chave por nome ou prefixo.
2. Escolha Revoke naquela linha de chave.
3. Atualize ou remova qualquer script ou integração que dependia dela.

A revogação entra em vigor imediatamente e não há um diálogo de confirmação separado, então confirme que a chave é a correta antes de escolher Revoke.

Cobrança

As chaves de API geradas consomem da mesma cota compartilhada de uso de chat e API mostrada em Billing. Verificações de pré-voo falhas e requisições upstream rejeitadas não devem consumir créditos; uma requisição transmitida torna-se cobrável quando o endpoint do Archibot aceita o stream. Consulte Cobrança e créditos do ArchibotChat.

Regras de segurança

• Nunca faça commit de chaves de API no controle de versão.
• Nunca cole chaves de API em tickets de suporte ou documentos compartilhados.
• Use variáveis de ambiente ou um gerenciador de segredos, não valores inline.
• Use uma chave por integração quando puder.
• Rotacione as chaves regularmente para integrações de longa duração.
• Revogue uma chave imediatamente se houver suspeita de exposição.

Credencial de chat versus chave de API

Não peça ao suporte da ISM para revelar a credencial de chat oculta. Ela é intencionalmente não visível ao usuário.

Guias relacionados

• Configuração do ArchibotChat
• Usando o ArchibotChat
• Cobrança e créditos do ArchibotChat
• Visão geral de segurança do ArchibotChat
• Uso de dados aprovado do ArchibotChat