Pular para o conteúdo
Turbo Notify

Chave de API

Para usar a API do Turbo Notify, você precisa de uma chave de API válida.

As chaves são gerenciadas pelo dashboard, onde você controla quem pode interagir com a sua conta e os seus números.

Inclusão

Gere novas chaves no dashboard, pelo menu API Keys (abre em nova aba) . A API não limita a quantidade de chaves, então você pode ter uma para cada sistema ou equipe.

O valor da chave aparece apenas uma vez, no momento da criação. Copie e guarde a chave imediatamente: não será possível vê-la de novo.

Cabeçalho

Toda requisição à API deve conter o cabeçalho Authorization com o valor da chave de API. Sem esse cabeçalho, nenhuma chamada é autorizada.

Authorization: Bearer SUA_CHAVE

Revogação

A revogação de uma chave de API é definitiva e irreversível. Não existe desativação temporária: uma vez revogada, a chave não pode ser reativada.

Revogue a chave pelo dashboard. A partir daí, toda requisição feita com ela é bloqueada permanentemente. A chave continua aparecendo na listagem com status revoked (para fins de auditoria), mas não volta a funcionar.

Se você precisa de uma pausa temporária no acesso, o caminho é gerar uma nova chave e revogar a antiga (rotação). Como não há limite de chaves por conta, você pode criar a nova, migrar suas integrações e só então revogar a anterior, sem janela de indisponibilidade.

Permissão

Não é possível limitar uma chave de API a um número específico: dentro dos escopos que carrega (veja Escopos), toda chave alcança o número principal da conta e todos os números extras.

Se você revende números para os seus clientes, mantenha a chave no servidor da sua plataforma e nunca a entregue a um cliente final. Identifique o número de cada cliente pelo id que a resposta do cadastro do número devolve: é a sua plataforma que decide qual cliente vê qual número. O guia de revenda mostra o fluxo completo.

Escopos

Cada chave carrega escopos de permissão que determinam quais operações ela pode chamar (por exemplo messages:send, messages:read, numbers:read, numbers:write, events:read, contacts:read, contacts:write, groups:read e organizations:read). A API distingue dois erros:

  • 401 not_authenticated: a chave está ausente, mal formatada, desconhecida, revogada ou expirada. A resposta traz o cabeçalho WWW-Authenticate: Bearer.
  • 403 insufficient_scope: a chave é válida, mas não possui o escopo exigido pelo endpoint. A resposta inclui o campo required_scope com o escopo necessário:
{
  "error": "insufficient_scope",
  "required_scope": "messages:send"
}

A tabela de erros de cada endpoint indica o escopo exigido pela operação.

Chave para um agente de IA

O Servidor MCP aceita entrar com a sua conta ou usar uma chave. Se o cliente do agente permite entrar (como o Claude e o Claude Code), prefira entrar: não há chave para guardar. Use uma chave em clientes que não permitem entrar e em agentes que rodam sozinhos, como um atendente 24 horas. Para isso, crie uma chave com o template Agente de IA (MCP) no dashboard. Ele marca só o necessário para um atendente: messages:send, messages:read, contacts:read, groups:read, numbers:read e events:read. O catálogo de ferramentas mostra o escopo de cada ferramenta, caso você queira ajustar a chave. Pelo servidor MCP, os dois erros acima chegam ao agente como unauthorized: not_authenticated e unauthorized: insufficient_scope, cada um com o que fazer em seguida.

Chave para revenda

Se a sua plataforma vende números aos próprios clientes, crie a chave com o template Revenda no dashboard. Ele marca numbers:read, numbers:write, messages:send, messages:read, contacts:read e events:read: o que a plataforma precisa para criar, parear e acompanhar um número por cliente e enviar e receber mensagens por eles. Atenção: numbers:write permite que a chave crie números, e cada número criado gera cobrança no cartão da conta. Veja o guia de revenda.

Relacionado