Pular para o conteúdo principal
Consulte URLs e autenticação HTTP e a referência da API para os formatos completos de solicitação e resposta.

Chaves de API

O que são chaves de API

As chaves de API são tokens que autenticam solicitações ao Toqan Router. Uma chave abrange um projeto ou todos os projetos do workspace quando criada sem projeto pela API. Suas permissões limitam o que ela pode fazer. Há dois tipos de chave disponíveis, definidos pelo proprietário da chave.

Chaves de usuário

Vinculadas a uma conta de usuário específica. São revogadas automaticamente se o usuário for removido da organização ou do projeto ao qual uma de suas chaves está vinculada. Use chaves de usuário para uso pessoal e desenvolvimento local.

Chaves de conta de serviço

Não são vinculadas a nenhum usuário individual e têm ciclo de vida independente da participação dos usuários. Apenas administradores do workspace podem criar chaves de conta de serviço. Use chaves de conta de serviço em sistemas de produção, para que o acesso não seja interrompido quando um membro da equipe sair.

Visualizar chaves de API

Acesse Settings > API Keys para ver todas as chaves de todos os projetos. A tabela mostra as seguintes colunas: Use o menu para filtrar por Type ou Permissions.

Criar uma chave de API

1

Abra o painel de criação

Acesse Settings > API Keys e selecione Secret key. O painel Create new secret key é aberto com os campos Owned by, Name, Project, Permissions e Expiration.
2

Escolha um proprietário

Em Owned by, selecione You para criar uma chave de usuário ou Service account para criar uma chave não vinculada a nenhum usuário individual.
3

Defina o nome e o projeto

Insira um Name para a chave e selecione o Project ao qual ela terá acesso.
4

Defina as permissões

Escolha uma predefinição de permissões. Consulte Permissões abaixo.
5

Defina a expiração (opcional)

Defina uma data em Expiration se a chave precisar ficar inativa automaticamente após uma determinada data.
6

Crie e copie a chave

Selecione Create secret key. Uma caixa de diálogo Save your key é exibida com o token e o resumo das permissões.Clique em Copy para copiar o token.
O token é exibido apenas uma vez. Armazene-o com segurança antes de fechar esta caixa de diálogo. Ele não poderá ser recuperado depois.
Para limitar o uso de custo, tokens ou solicitações por minuto de uma chave, vincule um Budget a ela. Os limites do orçamento são redefinidos no período configurado. Consulte Limites de taxa e cotas para saber o que o gateway aplica em cada camada.

Permissões

Com Restricted, defina a permissão de cada recurso individualmente: None, Read ou Write.
A permissão Write inclui automaticamente Read quando Read está disponível para o endpoint.

Gerenciar chaves

Selecione o menu em qualquer chave para acessar as seguintes ações:
  • Edit: atualiza o nome, as permissões ou a data de expiração. O tipo de proprietário não pode ser alterado após a criação.
  • Duplicate: abre o painel de criação preenchido com as configurações atuais da chave.
  • Delete: remove a chave permanentemente. Essa ação não pode ser desfeita.
O status Revoked significa que a chave pertencia a um usuário removido da organização ou do projeto, ou que foi revogada manualmente. A revogação é permanente.

Management Keys

Visão geral

As Management Keys estão disponíveis apenas para administradores do workspace. A página Management Keys não é visível para membros que não são administradores.
As Management Keys (chaves de gerenciamento) são tokens restritos ao workspace usados para autenticar operações de administração do workspace. Cada chave concede acesso de leitura ou escrita a cada recurso listado em Capacidades.
As Management Keys não podem ser usadas para consultar modelos ou agentes. Use uma chave de API padrão para endpoints de inferência e de produto.

Casos de uso

  • Automatizar o provisionamento do workspace pela API.
  • Delegar a rotação de chaves de API a um pipeline de implantação sem conceder acesso administrativo completo.
  • Permitir que um script de automação de faturamento leia e atualize Budgets sem expor o gerenciamento de chaves de API.

Endpoints de administração do workspace

Chaves de API não podem administrar chaves de API nem Budgets, portanto essas duas famílias exigem uma Management Key. O gerenciamento de projetos e de Smart Routers segue o escopo da chave: uma chave para todos os projetos pode criá-los, atualizá-los e excluí-los; uma chave de projeto único não pode.

Visualizar Management Keys

Abra Management Keys na barra lateral de Settings, em Organization, para ver todas as chaves do workspace. Clique em qualquer linha para abrir o painel de edição e atualizar o nome, as permissões ou a data de expiração da chave. Passe o cursor sobre uma linha e clique em para ver opções adicionais:
  • Edit: abre o painel de edição para atualizar o nome, as permissões ou a data de expiração da chave.
  • Duplicate: cria uma nova chave com as mesmas permissões.
  • Delete: remove a chave do workspace permanentemente.

Criar uma Management Key

1

Abra o painel de criação

Em Settings → Organization, abra Management Keys e clique em Key.
2

Insira um nome

Insira um Name para a chave (obrigatório, máximo de 128 caracteres).
3

Defina as permissões

Selecione um modo em Permissions; o padrão é All. Consulte Modos de permissão abaixo.
4

Defina a expiração (opcional)

Defina uma data em Expiration se a chave precisar deixar de autenticar após uma determinada data.
5

Crie e copie a chave

Clique em Create key. Um painel Save your key é exibido com o token.
O token é exibido apenas uma vez. Armazene-o com segurança antes de fechar este painel. Ele não poderá ser recuperado depois.

Modos de permissão

Capacidades

O modo Restricted mostra uma linha por capacidade. None não concede acesso a essa capacidade, Read lista e exibe seus recursos, e Write também cria, atualiza e exclui esses recursos. Um ✗ indica um nível que o seletor omite para essa capacidade, que então aceita apenas None ou Read.
As Management Keys não estão disponíveis via MCP. Use a API REST para gerenciar chaves programaticamente.

Gerenciar chaves programaticamente

Crie, atualize, revogue e exclua chaves de API e Management Keys pela API, em vez do console. A referência completa dos endpoints está nas páginas de referência de chaves de API e de referência de Management Keys.

Autenticar com uma Management Key

As solicitações de gerenciamento de chaves são autenticadas com uma Management Key, nunca com uma chave de API. As chaves de API são credenciais de inferência restritas aos recursos do projeto e não podem administrar chaves.
  • Passe uma Management Key como bearer token ou como chave de API do SDK.
  • Uma Management Key com a permissão de escrita api-key pode listar, criar, atualizar, revogar e excluir chaves de API.
O SDK expõe essas operações como api_keys / apiKeys e management_keys / managementKeys: SDK de chaves de API, SDK de Management Keys.

Ciclo de vida da chave no código

Estes exemplos usam uma Management Key como TOQAN_API_KEY. Crie uma chave restrita a um projeto com permissões restritas:
Desative, revogue ou exclua uma chave existente:
Para fazer a rotação de uma chave, crie uma chave substituta com a mesma configuração e, em seguida, revogue a antiga. A rotação consiste em criar e depois revogar; não há um endpoint dedicado para rotação.

Escopo de projeto

project_scope define quais projetos a chave alcança. Na criação, se você o omitir, a chave alcança todos os projetos do workspace. mode aceita os valores curtos all e single, ou os valores de enum PROJECT_SCOPE_MODE_ALL e PROJECT_SCOPE_MODE_SINGLE. A grafia aninhada alcança os mesmos escopos: {"all": {}} ou {"single": {"project_id": "..."}}. Envie uma única grafia por solicitação. projects é o array legado de um único elemento que clientes mais antigos enviam em vez de project_scope. Ele define um escopo de projeto único e, quando uma solicitação traz os dois campos, ambos devem indicar o mesmo projeto.

Modelo de permissões

permission_mode seleciona a predefinição: Com restricted, o mapa access atribui um nível a cada domínio. Write inclui read: O catálogo de capacidades lista os domínios que podem ser concedidos a uma chave: GET /v2/api-keys/capabilities retorna cada domínio com seu id, nome de exibição, grupo e disponibilidade de leitura / escrita. Use o catálogo para descobrir os domínios concedíveis em tempo de execução, em vez de fixar a lista no código. As chaves de access são os valores de id que o catálogo retorna (responses, model), e não os valores de display_name (Responses, Models). Por exemplo, uma chave restrita que pode executar Responses e ler o catálogo de modelos em todos os projetos:

O segredo é retornado uma única vez

A resposta de criação retorna o token bruto exatamente uma vez, no formato sk-orq-<id>-<secret>. Armazene-o imediatamente: a API guarda apenas um token_prefix exibível e um hash do segredo, portanto as respostas de listagem e de consulta nunca incluem o token.
O token é retornado apenas na resposta de criação. Armazene-o com segurança e trate-o como uma senha; ele não poderá ser recuperado depois.
Para saber como todos os outros tipos de segredo são armazenados, lidos e rotacionados, consulte Gerenciamento de segredos.

Limites de custo, tokens e taxa

As chaves não têm campos de limite. Vincule limites de custo, tokens e solicitações por minuto com um Budget restrito à chave. Os Budgets são recursos do workspace e exigem uma Management Key; chaves de API comuns não podem gerenciá-los.

Exemplo: provisionar uma chave por cliente com teto de gastos

Crie uma chave restrita ao projeto do cliente e, em seguida, vincule um teto de gastos mensal como um Budget restrito a essa chave: