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

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

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

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 #

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

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

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

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 â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:

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

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

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 chaves de API devolvem o envelope de erro padrão:

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

Os endpoints de chaves com âmbito definido adicionam alguns códigos nomeados no campo error_code para que possa distinguir os casos:

Próximos passos #

• Autenticação — as quatro formas de autenticar um pedido e como os âmbitos das chaves são aplicados.
• Erros e Limites de Taxa — códigos de estado e o limite de 300 pedidos/min.