# API da Chave de API Estes endpoints permitem-lhe gerir as chaves de API da sua conta a partir de código. Todos operam apenas sobre as chaves da própria conta que efetua a chamada. Existem dois tipos de chaves, que residem em caminhos separados: - **A sua chave principal** — a única chave de acesso total em **Definições → Integrações → Chave de API**. Consulte a sua pré-visualização mascarada, verifique a utilização do seu limite de taxa, rode-a ou revogue-a. Estes são os endpoints `/api-keys/current`, `/api-keys/rotate` e `/api-keys/usage` abaixo. - **Chaves com âmbito (Scoped keys)** — chaves adicionais com nome que cria para uma tarefa específica, cada uma limitada às partes da API que escolher. Estes são os endpoints `/api-keys` e `/api-keys/{id}` em [Chaves com âmbito](#scoped-keys). Nada muda na sua chave principal quando cria uma; as integrações existentes continuam inalteradas. Todos os caminhos abaixo são relativos ao URL base da API: ``` https://api.youraiconnector.com/v1 ``` Todos os pedidos devem ser autenticados. Consulte [Autenticação](authentication.md) para os quatro métodos aceites. Os exemplos aqui utilizam o cabeçalho `X-API-Key` (e uma forma de parâmetro de consulta para cURL). > **Leia isto primeiro.** A renovação ou revogação da sua chave entra em vigor **imediatamente**. No momento em que qualquer uma das chamadas é bem-sucedida, a chave antiga deixa de funcionar — todas as integrações que ainda a utilizam começam a receber erros `401`. Planeie isto: renove durante uma janela de manutenção e atualize todas as suas integrações imediatamente. --- ## Obter metadados da chave atual Devolve a sua chave ativa: a chave completa em `api_key` quando existe uma cópia recuperável, uma pré-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 de as cópias recuperáveis serem guardadas — rode uma vez e a nova chave poderá ser mostrada 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 é `404` com `{ "success": false, "error": "No API key found for this account" }`. --- ## Obter utilização do limite de taxa Devolve a utilização do seu limite de taxa para a janela atual: o limite de pedidos por janela, quantos pedidos foram contabilizados até ao momento, quantos restam e quando a janela é reiniciada. Utilize isto para criar uma limitação do lado do cliente, para que a sua integração abrande antes de atingir 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 ainda não tiverem sido registados pedidos na janela atual, a utilização é reportada como zero e a resposta inclui um campo `note` a explicar o motivo. --- ## Renovar a chave Gera uma nova chave de API e invalida a anterior no mesmo passo. Utilize isto se suspeitar que a sua chave foi exposta, ou como parte de uma política regular de renovação de credenciais. `POST /api-keys/rotate` > **A nova chave é apresentada apenas uma vez.** É devolvida nesta resposta e não pode ser recuperada na íntegra posteriormente — guarde-a de forma segura no momento em que a receber. A chave anterior deixa de funcionar no instante em que este pedido é bem-sucedido, por isso 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 Elimina permanentemente a chave de API da sua conta. A revogação é imediata: todos os pedidos subsequentes que utilizem a chave revogada — incluindo integrações como o Make, Zapier ou scripts personalizados — são rejeitados com um `401`. Para restaurar o acesso à API posteriormente, gere uma nova chave a partir das definições da sua conta enquanto tem sessão iniciada na aplicação. `DELETE /api-keys/current` > **Não existe opção de anular.** Ao contrário da rotação, a revogação não lhe fornece uma chave de substituição. Apenas revogue quando pretender interromper o acesso à API (por exemplo, uma chave comprometida que 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 nenhuma chave para revogar, a resposta é `404`. --- ## Chaves com âmbito Uma chave com âmbito é uma chave de API adicional que cria para uma tarefa específica, contendo apenas o acesso de que essa tarefa necessita. O caso clássico: pretende ligar um dashboard de cliente, uma ferramenta de relatórios ou um script interno à sua conta sem entregar uma chave que também possa enviar mensagens, alterar os seus agentes de IA ou comprar um número de telefone. A restrição acompanha a própria chave, pelo que quem a detiver só pode fazer o que permitiu quando a criou. **O que pode restringir** | Campo | O que significa | |---|---| | `read_only` | `true` (o padrão) significa que apenas pedidos de leitura são permitidos. Qualquer criação, atualização ou eliminação é recusada. | | `tags` | A lista de secções da API que a chave pode utilizar, escrita com os mesmos nomes de secção que vê nestes documentos e no [explorador de API](reference.md) — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments`, etc. Uma lista vazia significa todas as secções. | | `sub_account_ids` | Em que contas geridas a chave pode atuar. Vazio significa apenas a sua própria conta; `["*"]` significa qualquer conta que realmente gere. A propriedade é sempre verificada em cada pedido. | | `rate_limit_per_min` | Pedidos por minuto para esta chave, contados no seu próprio orçamento para que não possa esgotar a quota das suas outras integrações. O padrão é `60` e não pode ser definido acima de `300`. | Também pode atribuir a uma chave uma data de `expires_at` (ISO 8601, e deve ser no futuro). Após esse momento, a chave deixa de funcionar por si só. Deixe em branco e a chave nunca expira até que a revogue. > **As recusas são definitivas.** Se um pedido estiver fora do que a chave permite, é recusado em vez de ser aceite: uma escrita com uma chave de apenas leitura devolve `403` com `error_code: "key_read_only"`, e qualquer coisa fora das secções permitidas da chave devolve `403` com `error_code: "key_scope_denied"`. Se uma chave com âmbito receber um `403` inesperado, o endpoint que chamou simplesmente não está dentro dos seus âmbitos — alargue a chave ou utilize a sua chave principal. > **Apenas o proprietário da conta gere as chaves.** Estes quatro endpoints requerem a sua chave principal ou uma sessão de proprietário na aplicação. Uma chave com âmbito nunca pode listar, criar, editar ou revogar chaves — incluindo a si própria — pelo que uma chave restrita nunca pode ser usada para criar uma mais abrangente. Tentar fazê-lo devolve `403` com `error_code: "key_scope_denied"`. Pela mesma razão, `API Keys` não é uma secção que possa conceder: pedir isso devolve `400` com `error_code: "invalid_scopes"`. ### Listar chaves com âmbito Devolve as chaves com âmbito da conta, da mais recente para a mais antiga (até 200), incluindo as revogadas para que possa ver o que foi retirado e quando. Apenas são devolvidas pré-visualizações mascaradas — o valor de uma chave com âmbito é mostrado uma vez, na criação, e nunca mais pode ser recuperado. `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 âmbito Cria uma nova chave com âmbito e devolve o seu valor **uma única vez**. `POST /api-keys` > **A chave é apresentada apenas uma vez.** Encontra-se nesta resposta e em mais lado nenhum, nunca — não existe forma de a consultar posteriormente. Guarde-a no momento em que a recebe. Se a perder, revogue-a e crie outra. **Campos do corpo** — todos opcionais: | Campo | Tipo | Notas | |---|---|---| | `label` | string | O seu próprio nome para a chave, apresentado na lista e nas Definições. | | `scopes` | object | Os quatro campos na tabela acima. Se omitir o objeto completo, obterá a predefinição segura: apenas de leitura, limitada a `Analytics`, apenas para a sua conta, 60 pedidos 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 conhecer ao desenvolver com base nisto: - **Omitir `scopes` não é o mesmo que enviar uma lista `tags` vazia.** Deixe `scopes` de fora por completo e obterá a predefinição segura (apenas de leitura, apenas `Analytics`). Envie `"tags": []` propositadamente e a chave poderá utilizar todas as secções — isto é lido como um pedido deliberado para uma chave sem restrições. - **`read_only` permanece `true` a menos que envie explicitamente `false`.** Um erro de digitação ou um sinalizador em falta nunca podem produzir acidentalmente uma chave com permissões de escrita. ### Atualizar uma chave com âmbito Altera a etiqueta, os âmbitos e/ou a expiração de uma chave. Envie qualquer combinação dos três; enviar nenhum deles devolve `400`. `PATCH /api-keys/{id}` O `{id}` é o `id` da chave a partir da lista (o valor `key_...`), nunca a própria chave. > **Os âmbitos são substituídos, não fundidos.** O que quer que envie torna-se o conjunto completo de permissões da chave. Isto é deliberado: restringir uma chave nunca pode deixar silenciosamente o acesso antigo e mais abrangente em vigor. Envie sempre o objeto `scopes` completo que pretende, não apenas o campo que está a alterar. O valor da chave nunca muda. Não existe rotação no local para uma chave com âmbito — para renovar uma, crie uma nova chave e revogue a antiga, para que o acesso de uma credencial nunca possa mudar numa integração que ainda a detenha. **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 existir nenhuma chave com esse id na sua conta, a resposta é `404`. ### Revogar uma chave com âmbito definido A revogação é imediata: o pedido seguinte que utilize essa chave é rejeitado com um `401`. A sua chave principal e todas as outras chaves com âmbito definido permanecem inalteradas. `DELETE /api-keys/{id}` A chave permanece na sua lista marcada como `"revoked": true`, para que mantenha o registo do que existia e do que podia aceder. Revogar uma chave que já se encontra revogada é uma operação bem-sucedida que 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 chaves de API devolvem o envelope de erro padrão: ```json { "success": false, "error": "No API key found for this account" } ``` Num endpoint de chave de API, uma chave em falta ou inválida devolve `401` e uma conta sem chave registada devolve `404`. Os códigos partilhados que qualquer endpoint pode devolver — `400`, `403` (o seu plano não inclui acesso à API), `429` (limite de taxa) e `500` — estão listados com orientações de repetição em [Erros e Paginação](errors-and-pagination.md). Os endpoints de chaves com âmbito definido adicionam alguns códigos nomeados no campo `error_code` para que possa distinguir os casos: | `error_code` | Estado | O que aconteceu | |---|---|---| | `key_read_only` | `403` | Uma chave apenas de leitura tentou efetuar uma escrita. | | `key_scope_denied` | `403` | A chave não é permitida nesse endpoint ou nessa conta gerida — ou uma chave com âmbito definido tentou gerir chaves de API, o que nunca é permitido. | | `invalid_scopes` | `400` | Os âmbitos solicitados incluíam a secção `API Keys`. As chaves não podem gerir chaves. | | `404` | `404` | Não existe nenhuma chave com esse id na sua conta. | --- ## Próximos passos - [Autenticação](authentication.md) — as quatro formas de autenticar um pedido e como os âmbitos das chaves são aplicados. - [Erros e Limites de Taxa](errors-and-pagination.md) — códigos de estado e o limite de 300 pedidos/min.