# API de Chaves de API Estes endpoints permitem que você gerencie as chaves de API da sua conta via código. Todos eles operam apenas nas chaves da própria conta que realiza a chamada. Existem dois tipos de chave, e elas residem em caminhos separados: - **Sua chave principal** — a única chave de acesso total em **Configurações → Integrações → Chave de API**. Consulte sua visualização mascarada, verifique o uso do seu limite de taxa, rotacione-a ou revogue-a. Estes são os endpoints `/api-keys/current`, `/api-keys/rotate` e `/api-keys/usage` abaixo. - **Chaves com escopo** — chaves extras e nomeadas que você cria para uma tarefa específica, cada uma limitada às partes da API que você escolher. Estes são os endpoints `/api-keys` e `/api-keys/{id}` em [Chaves com escopo](#scoped-keys). Nada sobre sua chave principal muda quando você cria uma; as integrações existentes continuam inalteradas. Todos os caminhos abaixo são relativos à URL base da API: ``` https://api.youraiconnector.com/v1 ``` Cada solicitação deve ser autenticada. Consulte [Autenticação](authentication.md) para os quatro métodos aceitos. Os exemplos aqui usam o cabeçalho `X-API-Key` (e uma forma de parâmetro de consulta para cURL). > **Leia isto primeiro.** Rotacionar ou revogar sua chave entra em vigor **imediatamente**. No momento em que qualquer uma das chamadas for bem-sucedida, a chave antiga para de funcionar — toda integração que ainda a utiliza começará a receber erros `401`. Planeje-se: rotacione durante uma janela de manutenção e atualize todas as suas integrações imediatamente. --- ## Obter metadados da chave atual Retorna sua chave ativa: a chave completa em `api_key` quando uma cópia recuperável existe, uma visualização mascarada (primeiros 4 e últimos 4 caracteres) e, quando disponível, a data em que foi criada. `api_key` é `null` para chaves criadas antes que cópias recuperáveis fossem mantidas — gire uma vez e a nova chave poderá ser exibida novamente mais tarde. `GET /api-keys/current` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/api-keys/current", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Resposta** ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "api_key_masked": "abcd...qrst", "created_at": "2026-06-01T10:00:00.000Z" } ``` Se a conta não tiver uma chave de API, a resposta será `404` com `{ "success": false, "error": "No API key found for this account" }`. --- ## Obter uso do limite de taxa Retorna o uso do seu limite de taxa para a janela atual: o limite de solicitações por janela, quantas solicitações foram contabilizadas até o momento, quantas restam e quando a janela será redefinida. Use isso para criar um controle de fluxo no lado do cliente, para que sua integração reduza o ritmo antes de atingir as respostas `429`. `GET /api-keys/usage` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys/usage" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/usage", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/api-keys/usage", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Resposta** ```json { "success": true, "usage": { "limit": 300, "window_seconds": 60, "used": 37, "remaining": 263, "window_resets_at": "2026-06-09T12:01:00.000Z" } } ``` Se nenhuma solicitação tiver sido registrada na janela atual, o uso é relatado como zero e a resposta inclui um campo `note` explicando o motivo. --- ## Rotacionar a chave Gera uma nova chave de API e invalida a anterior na mesma etapa. Use isso se suspeitar que sua chave vazou, ou como parte de uma política regular de rotação de credenciais. `POST /api-keys/rotate` > **A nova chave é exibida apenas uma vez.** Ela é retornada nesta resposta e não pode ser recuperada integralmente depois — armazene-a com segurança no momento em que a receber. A chave anterior para de funcionar no instante em que esta chamada é bem-sucedida, portanto, atualize todas as integrações que a utilizavam. **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); // Save data.api_key now — it will not be shown again. ``` **Python** ```python import requests res = requests.post( "https://api.youraiconnector.com/v1/api-keys/rotate", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() # Save data["api_key"] now — it will not be shown again. ``` **Resposta** ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again." } ``` --- ## Revogar a chave Exclui permanentemente a chave de API da sua conta. A revogação é imediata: toda solicitação subsequente que utilize a chave revogada — incluindo integrações como Make, Zapier ou scripts personalizados — é rejeitada com um `401`. Para restaurar o acesso à API posteriormente, gere uma nova chave nas configurações da sua conta enquanto estiver conectado ao aplicativo. `DELETE /api-keys/current` > **Não há como desfazer.** Ao contrário da rotação, a revogação não fornece uma chave de substituição. Revogue apenas quando pretender interromper o acesso à API (por exemplo, uma chave vazada que você não pode substituir imediatamente). **cURL** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.delete( "https://api.youraiconnector.com/v1/api-keys/current", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Resposta** ```json { "success": true, "revoked": true, "message": "API key revoked. All requests using it will be rejected immediately." } ``` Se a conta não tiver uma chave para revogar, a resposta será `404`. --- ## Chaves com escopo Uma chave com escopo é uma chave de API extra que você cria para uma tarefa específica, contendo apenas o acesso que essa tarefa precisa. O caso clássico: você deseja apontar um painel de cliente, uma ferramenta de relatório ou um script interno para sua conta sem entregar uma chave que também poderia enviar mensagens, alterar seus agentes de IA ou comprar um número de telefone. A restrição acompanha a própria chave, portanto, quem a possuir só poderá fazer o que você permitiu quando a criou. **O que você pode restringir** | Campo | O que significa | |---|---| | `read_only` | `true` (o padrão) significa que apenas solicitações de leitura são permitidas. Qualquer criação, atualização ou exclusão é recusada. | | `tags` | A lista de seções da API que a chave pode usar, escrita com os mesmos nomes de seção que você vê nestes documentos e no [explorador de API](reference.md) — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments`, e assim por diante. Uma lista vazia significa todas as seções. | | `sub_account_ids` | Em quais contas gerenciadas a chave pode atuar. Vazio significa apenas sua própria conta; `["*"]` significa qualquer conta que você realmente gerencia. A propriedade ainda é verificada em cada solicitação. | | `rate_limit_per_min` | Solicitações por minuto para esta chave, contadas em seu próprio orçamento para que não possa consumir a franquia de suas outras integrações. O padrão é `60`, e não pode ser definido acima de `300`. | Você também pode dar a uma chave uma data de `expires_at` (ISO 8601, e deve ser no futuro). Após esse momento, a chave para de funcionar por conta própria. Deixe em branco e a chave nunca expirará até que você a revogue. > **Negações falham de forma fechada.** Se uma solicitação estiver fora do que a chave permite, ela será recusada em vez de permitida: uma gravação com uma chave somente leitura retorna `403` com `error_code: "key_read_only"`, e qualquer coisa fora das seções permitidas da chave retorna `403` com `error_code: "key_scope_denied"`. Se uma chave com escopo receber um `403` inesperado, o endpoint que você chamou simplesmente não está dentro de seus escopos — amplie a chave ou use sua chave principal. > **Apenas o proprietário da conta gerencia chaves.** Estes quatro endpoints exigem sua chave principal ou uma sessão de proprietário no aplicativo. Uma chave com escopo nunca pode listar, criar, editar ou revogar chaves — incluindo a si mesma — portanto, uma chave restrita nunca pode ser usada para criar uma mais ampla. Tentar retorna `403` com `error_code: "key_scope_denied"`. Pelo mesmo motivo, `API Keys` não é uma seção que você pode conceder: solicitar isso retorna `400` com `error_code: "invalid_scopes"`. ### Listar chaves com escopo Retorna as chaves com escopo da conta, da mais recente para a mais antiga (até 200), incluindo as revogadas para que você possa ver o que foi retirado e quando. Apenas visualizações mascaradas são retornadas — o valor de uma chave com escopo é mostrado uma vez, na criação, e nunca pode ser recuperado posteriormente. `GET /api-keys` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys" \ -H "X-API-Key: YOUR_API_KEY" ``` **Resposta** ```json { "success": true, "api_keys": [ { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 }, "expires_at": null, "last_used_at": "2026-08-20T14:03:00.000Z", "created_at": "2026-08-14T09:12:00.000Z", "revoked_at": null, "revoked": false } ] } ``` ### Criar uma chave com escopo Cria uma nova chave com escopo e retorna seu valor **uma única vez**. `POST /api-keys` > **A chave é exibida apenas uma vez.** Ela está nesta resposta e em nenhum outro lugar, nunca — não há como consultá-la novamente depois. Armazene-a no momento em que a receber. Se você a perder, revogue-a e crie outra. **Campos do corpo** — todos opcionais: | Campo | Tipo | Notas | |---|---|---| | `label` | string | Seu próprio nome para a chave, exibido na lista e em Configurações. | | `scopes` | object | Os quatro campos na tabela acima. Deixe o objeto inteiro de fora e você obterá o padrão seguro: somente leitura, limitado a `Analytics`, apenas sua própria conta, 60 requisições por minuto. | | `expires_at` | data ISO 8601 | Expiração opcional, deve ser uma data futura. | **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/api-keys" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Client dashboard - Acme", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 } }' ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ label: "Client dashboard - Acme", scopes: { read_only: true, tags: ["Analytics"] }, }), }); const data = await res.json(); // Save data.api_key now — it will not be shown again. ``` **Python** ```python import requests res = requests.post( "https://api.youraiconnector.com/v1/api-keys", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "label": "Client dashboard - Acme", "scopes": {"read_only": True, "tags": ["Analytics"]}, }, ) data = res.json() # Save data["api_key"] now — it will not be shown again. ``` **Resposta** — `201 Created` ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "key": { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 }, "expires_at": null, "revoked": false }, "message": "Store this key now — it is shown once and cannot be retrieved again." } ``` Alguns detalhes que vale a pena saber ao desenvolver com isso: - **Omitir `scopes` não é o mesmo que enviar uma lista `tags` vazia.** Deixe `scopes` de fora completamente e você obterá o padrão seguro (somente leitura, apenas `Analytics`). Envie `"tags": []` propositalmente e a chave poderá usar todas as seções — isso é lido como uma solicitação deliberada de uma chave sem restrições. - **`read_only` permanece `true` a menos que você envie explicitamente `false`.** Um erro de digitação ou uma flag ausente nunca pode produzir acidentalmente uma chave que possa escrever. ### Atualizar uma chave com escopo Altera o rótulo, os escopos e/ou a expiração de uma chave. Envie qualquer combinação dos três; enviar nenhum deles retorna `400`. `PATCH /api-keys/{id}` O `{id}` é o `id` da chave na lista (o valor `key_...`), nunca a chave em si. > **Os escopos são substituídos, não mesclados.** O que você enviar se torna o conjunto completo de permissões da chave. Isso é deliberado: restringir uma chave nunca pode deixar silenciosamente o acesso antigo e mais amplo em vigor. Sempre envie o objeto `scopes` completo que você deseja, não apenas o campo que está alterando. O valor da chave nunca muda. Não existe rotação no local para uma chave com escopo — para renovar uma, crie uma nova chave e revogue a antiga, para que o acesso de uma credencial nunca possa mudar sob uma integração que ainda a possua. **cURL** ```bash curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Client dashboard - Acme (read-only)", "scopes": { "read_only": true, "tags": ["Analytics", "Campaigns"], "sub_account_ids": [], "rate_limit_per_min": 30 } }' ``` **Resposta** ```json { "success": true, "key": { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme (read-only)", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics", "Campaigns"], "sub_account_ids": [], "rate_limit_per_min": 30 }, "expires_at": null, "last_used_at": "2026-08-20T14:03:00.000Z", "created_at": "2026-08-14T09:12:00.000Z", "revoked_at": null, "revoked": false } } ``` Se não houver uma chave com esse id em sua conta, a resposta será `404`. ### Revogar uma chave com escopo A revogação é imediata: a próxima solicitação que usar essa chave será rejeitada com um `401`. Sua chave principal e todas as outras chaves com escopo não são afetadas. `DELETE /api-keys/{id}` A chave permanece em sua lista marcada como `"revoked": true`, para que você mantenha o registro do que existia e do que ela podia acessar. Revogar uma chave que já foi revogada é bem-sucedido e não altera nada. **cURL** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \ -H "X-API-Key: YOUR_API_KEY" ``` **Resposta** ```json { "success": true, "revoked": true, "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "message": "API key revoked. All requests using it will be rejected immediately." } ``` --- ## Erros da API de Chaves de API Os endpoints de chave de API retornam o envelope de erro padrão: ```json { "success": false, "error": "No API key found for this account" } ``` Em um endpoint de chave de API, uma chave ausente ou inválida retorna `401` e uma conta sem chave registrada retorna `404`. Os códigos compartilhados que cada endpoint pode retornar — `400`, `403` (seu plano não inclui acesso à API), `429` (limite de taxa) e `500` — estão listados com orientações de nova tentativa em [Erros e Paginação](errors-and-pagination.md). Os endpoints de chaves com escopo adicionam alguns códigos nomeados no campo `error_code` para que você possa distinguir os casos: | `error_code` | Status | O que aconteceu | |---|---|---| | `key_read_only` | `403` | Uma chave somente leitura tentou realizar uma gravação. | | `key_scope_denied` | `403` | A chave não é permitida nesse endpoint ou nessa conta gerenciada — ou uma chave com escopo tentou gerenciar chaves de API, o que nunca é permitido. | | `invalid_scopes` | `400` | Os escopos solicitados incluíam a seção `API Keys`. Chaves não podem gerenciar chaves. | | `404` | `404` | Nenhuma chave com esse id em sua conta. | --- ## Próximos passos - [Autenticação](authentication.md) — as quatro maneiras de autenticar uma solicitação e como os escopos de chave são aplicados. - [Erros e Limites de Taxa](errors-and-pagination.md) — códigos de status e o limite de 300 req/min.