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. 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 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

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "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

curl "https://api.youraiconnector.com/v1/api-keys/usage" \
  -H "X-API-Key: YOUR_API_KEY"

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/usage",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "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

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

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

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

{
  "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

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \
  -H "X-API-Key: YOUR_API_KEY"

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

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "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

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

curl "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "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:

cURL

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

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

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

{
  "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

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

{
  "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

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "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:

{
  "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.

Os endpoints de chaves com escopo adicionam alguns códigos nomeados no campo error_code para que você possa distinguir os casos:

Próximos passos #

• Autenticação — as quatro maneiras de autenticar uma solicitação e como os escopos de chave são aplicados.
• Erros e Limites de Taxa — códigos de status e o limite de 300 req/min.