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.
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.
Recursos da permissão Restricted
Recursos da permissão Restricted
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.
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.
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-keypode listar, criar, atualizar, revogar e excluir chaves de API.
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 comoTOQAN_API_KEY.
Crie uma chave restrita a um projeto com permissões restritas:
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 formatosk-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.
Para saber como todos os outros tipos de segredo são armazenados, lidos e rotacionados, consulte Gerenciamento de segredos.

