> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Chaves de API e Management Keys > Crie e gerencie chaves de API e Management Keys restritas ao workspace no Toqan Router, com permissões granulares para usuários e contas de serviço. Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) 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](/docs/pt-BR/reference/api-keys/create-a-new-api-key.md). 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: | Coluna | Descrição | | - | - | | **Created** | Data de criação da chave | | **Name** | Rótulo da chave | | **Project** | O projeto que a chave pode acessar | | **Type** | `User` ou `Service` | | **Status** | `Active`, `Disabled` ou `Revoked` | | **Permissions** | `All`, `Read only` ou `Restricted` | | **Expiration** | Quando a chave deixa de autenticar, ou `No expiration` | | **Created by** | Usuário que criou a chave | 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](#permissions) 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. > [!WARNING] > > 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. > [!NOTE] > > Para limitar o uso de **custo**, **tokens** ou **solicitações por minuto** de uma chave, vincule um [Budget](/docs/pt-BR/ai-gateway/budgets.md) a ela. Os limites do orçamento são redefinidos no período configurado. Consulte [Limites de taxa e cotas](/docs/pt-BR/ai-gateway/features/rate-limits.md) para saber o que o gateway aplica em cada camada. ### Permissões | Predefinição | Descrição | | - | - | | **All** | Acesso de leitura e escrita a todos os recursos da API | | **Read only** | Acesso de leitura a todos os recursos da API | | **Restricted** | Acesso personalizado por recurso | Com **Restricted**, defina a permissão de cada recurso individualmente: **None**, **Read** ou **Write**. > [!NOTE] > > A permissão **Write** inclui automaticamente **Read** quando Read está disponível para o endpoint. > [accordion] Recursos da permissão Restricted > > | Recurso | None | Read | Write | > | - | :-: | :-: | :-: | > | Agent schedules | ✓ | ✓ | ✓ | > | Agents | ✓ | ✓ | ✓ | > | Annotations | ✓ | ✓ | ✓ | > | Chunking | ✓ | ✓ | ✓ | > | Datasets | ✓ | ✓ | ✓ | > | Deployments | ✓ | ✓ | ✓ | > | Evaluators | ✓ | ✓ | ✓ | > | External agents | ✓ | ✓ | ✓ | > | Feedback | ✓ | ✓ | ✓ | > | Files | ✓ | ✓ | ✓ | > | Guardrail rules | ✓ | ✓ | ✓ | > | Human evaluations | ✓ | ✓ | ✓ | > | Identities | ✓ | ✓ | ✓ | > | Knowledge bases | ✓ | ✓ | ✓ | > | Memory stores | ✓ | ✓ | ✓ | > | Policies | ✓ | ✓ | ✓ | > | Projects | ✓ | ✓ | ✓ | > | Prompts | ✓ | ✓ | ✓ | > | Reporting | ✓ | ✓ | | > | Routing rules | ✓ | ✓ | ✓ | > | SCIM | ✓ | ✓ | ✓ | > | Skills | ✓ | ✓ | ✓ | > | Tools | ✓ | ✓ | ✓ | > | **Gateway** | | | | > | Batches | ✓ | | ✓ | > | Chat completions | ✓ | | ✓ | > | Classify | ✓ | | ✓ | > | Embeddings | ✓ | | ✓ | > | Images | ✓ | | ✓ | > | Models | ✓ | ✓ | | > | Moderations | ✓ | | ✓ | > | OCR | ✓ | | ✓ | > | Rerank | ✓ | | ✓ | > | Responses | ✓ | ✓ | ✓ | > | Speech | ✓ | | ✓ | > | Transcriptions | ✓ | | ✓ | ### 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. > [!NOTE] > > 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 > [!NOTE] > > 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](#capabilities). > [!TIP] > > 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. | Família de endpoints | Acesso | | - | - | | `/v2/api-keys*` | Listar, consultar, criar, atualizar e excluir chaves de API. `/v2/api-keys/capabilities` é público. | | `/v2/budgets*` | Listar, consultar, criar, atualizar, redefinir e excluir Budgets. | | `/v2/projects*` | Uma chave de API para todos os projetos gerencia os projetos de todo o workspace; uma chave de projeto único só pode listar ou consultar o próprio projeto. | | `/v2/smart-routers*` | Uma chave de API para todos os projetos lista, cria, atualiza, ativa, desativa e exclui Smart Routers em todo o workspace. | ### 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](#permission-modes) 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. > [!WARNING] > > 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 | Modo | Descrição | | - | - | | **All** | Acesso completo de leitura e escrita a todas as capacidades. | | **Restricted** | Configure o acesso por capacidade. Cada capacidade pode ser definida como None, Read ou Write de forma independente. | | **Read only** | Acesso de leitura a todas as capacidades. | #### 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. | Capacidade | Read | Write | | - | :-: | :-: | | API keys | ✓ | ✓ | | Audit logs | ✓ | ✗ | | Budgets | ✓ | ✓ | | Environments | ✓ | ✓ | | Evaluators | ✓ | ✓ | | Guardrail rules | ✓ | ✓ | | Hub | ✓ | ✗ | | Logs | ✓ | ✗ | | Management keys | ✓ | ✓ | | MCP gateways | ✓ | ✓ | | MCP servers | ✓ | ✓ | | Model fusions | ✓ | ✓ | | Models | ✓ | ✓ | | Notifiers | ✓ | ✓ | | Policies | ✓ | ✓ | | Projects | ✓ | ✓ | | Reporting | ✓ | ✗ | | Routing rules | ✓ | ✓ | | Secrets | ✓ | ✓ | | Smart routers | ✓ | ✓ | | Teams | ✓ | ✓ | | Traces | ✓ | ✗ | | Users | ✓ | ✓ | | Vaults | ✓ | ✓ | | Workspace | ✓ | ✓ | | Workspace models | ✓ | ✓ | > [!NOTE] > > 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](/docs/pt-BR/reference/api-keys/create-a-new-api-key.md) e de [referência de Management Keys](/docs/pt-BR/reference/management-keys/create-a-new-management-key.md). ### 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`. | Operação | Endpoint | Observações | | - | - | - | | Criar | `POST /v2/api-keys` | `name` é obrigatório; escopo, permissões e expiração são opcionais. Se `permission_mode` for omitido, o padrão é `all`, que concede acesso de leitura e escrita a todas as capacidades | | Desativar | `PATCH /v2/api-keys/{api_key_id}` | Defina `status` como `disabled`; reversível | | Revogar | `PATCH /v2/api-keys/{api_key_id}` | Defina `status` como `revoked`; permanente | | Excluir | `DELETE /v2/api-keys/{api_key_id}` | Remove a chave permanentemente | | Listar | `GET /v2/api-keys` | Paginado; nunca retorna o segredo | | Consultar | `GET /v2/api-keys/{api_key_id}` | Nunca retorna o segredo | Crie uma chave restrita a um projeto com permissões restritas: ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST https://router.toqan.ai/eu/v2/api-keys \ -H "Authorization: Bearer $TOQAN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Support automation key", "project_scope": { "mode": "single", "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V" }, "permission_mode": "restricted", "access": { "agent": "write", "deployment": "read" } }' ``` Desative, revogue ou exclua uma chave existente: ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} # Disable (reversible) curl -X PATCH https://router.toqan.ai/eu/v2/api-keys/01HZXW2K7Y8Q9M0N1P2R3S4T5V \ -H "Authorization: Bearer $TOQAN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status": "disabled"}' # Revoke (permanent) curl -X PATCH https://router.toqan.ai/eu/v2/api-keys/01HZXW2K7Y8Q9M0N1P2R3S4T5V \ -H "Authorization: Bearer $TOQAN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status": "revoked"}' # Delete curl -X DELETE https://router.toqan.ai/eu/v2/api-keys/01HZXW2K7Y8Q9M0N1P2R3S4T5V \ -H "Authorization: Bearer $TOQAN_API_KEY" ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} // Disable (reversible) await client.apiKeys.update({ apiKeyId: "01HZXW2K7Y8Q9M0N1P2R3S4T5V", updateApiKeyRequest: { status: "disabled" }, }); // Revoke (permanent) await client.apiKeys.update({ apiKeyId: "01HZXW2K7Y8Q9M0N1P2R3S4T5V", updateApiKeyRequest: { status: "revoked" }, }); // Delete await client.apiKeys.delete({ apiKeyId: "01HZXW2K7Y8Q9M0N1P2R3S4T5V" }); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} # Disable (reversible) client.api_keys.update( api_key_id="01HZXW2K7Y8Q9M0N1P2R3S4T5V", status="disabled", ) # Revoke (permanent) client.api_keys.update( api_key_id="01HZXW2K7Y8Q9M0N1P2R3S4T5V", status="revoked", ) # Delete client.api_keys.delete(api_key_id="01HZXW2K7Y8Q9M0N1P2R3S4T5V") ``` 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` | `project_id` | Efeito | | - | - | - | | `all` | Omitido | A chave alcança todos os projetos do workspace. | | `single` | Obrigatório | A chave alcança apenas esse projeto. | `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: | Modo | Descrição | | - | - | | `all` | Acesso de leitura e escrita a todos os domínios do catálogo de capacidades de chaves de API | | `read_only` | Acesso de leitura a todos os domínios do catálogo de capacidades de chaves de API | | `restricted` | Acesso por domínio por meio do mapa `access` | Com `restricted`, o mapa `access` atribui um nível a cada domínio. Write inclui read: | Nível | Acesso | | - | - | | `none` | Sem acesso | | `read` | Acesso de leitura | | `write` | Acesso de leitura e escrita | 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: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "name": "Support automation key", "permission_mode": "restricted", "access": { "responses": "write", "model": "read" } } ``` ### O segredo é retornado uma única vez A resposta de criação retorna o token bruto exatamente uma vez, no formato `sk-orq--`. 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. > [!WARNING] > > 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](/docs/pt-BR/ai-gateway/budgets.md) 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: ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} # Create the customer key; capture the key id and token from the response curl -X POST https://router.toqan.ai/eu/v2/api-keys \ -H "Authorization: Bearer $TOQAN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Acme key", "project_scope": { "mode": "single", "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V" }, "permission_mode": "restricted", "access": { "agent": "write" } }' # Cap cost, tokens, and rate with a Budget scoped to the key curl -X POST https://router.toqan.ai/eu/v2/budgets \ -H "Authorization: Bearer $TOQAN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "scope": { "api_key": { "api_key_id": "" } }, "limits": { "period": "BUDGET_PERIOD_MONTHLY", "amount": 100, "token_limit": 1000000 }, "rate_limit": { "requests_per_minute": 60 } }' ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} const key = await client.apiKeys.create({ name: "Customer Acme key", projectScope: { mode: "single", projectId: "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V", }, permissionMode: "restricted", access: { agent: "write", }, }); console.log(key.token); await client.budgets.create({ scope: { apiKey: { apiKeyId: key.id } }, limits: { period: "BUDGET_PERIOD_MONTHLY", amount: 100, tokenLimit: 1000000, }, rateLimit: { requestsPerMinute: 60 }, }); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} key = client.api_keys.create( name="Customer Acme key", project_scope={ "mode": "single", "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V", }, permission_mode="restricted", access={ "agent": "write", }, ) print(key.token) client.budgets.create( scope={"api_key": {"api_key_id": key.id}}, limits={ "period": "BUDGET_PERIOD_MONTHLY", "amount": 100, "token_limit": 1000000, }, rate_limit={"requests_per_minute": 60}, ) ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.