Autenticação

Toda chamada à API leva a chave de API num cabeçalho Authorization, no formato Bearer:

Authorization: Bearer <sua-chave>

A chave é criada e revogada pelo dono da empresa em Configurações, aba API; veja Chaves de API para como criar uma e o que cada permissão faz. Ela não expira sozinha: fica válida até ser revogada.

Escopos

Cada chave carrega uma lista de permissões (escopos), escolhida na criação de cada uma. Um endpoint que exige um escopo que a chave não tem devolve 403 com o código forbidden_scope, mesmo com uma chave válida.

Escopo	Libera
channels:read	GET /v1/channels
templates:read	GET /v1/templates
messages:send	POST /v1/messages/text, POST /v1/messages/media, POST /v1/messages/template
messages:read	GET /v1/messages/{id}
files:write	POST /v1/files
files:read	GET /v1/files

GET /v1/me não exige nenhum escopo: qualquer chave válida pode chamá-lo.

GET /v1/me

Devolve o que aquela chave pode fazer agora: útil para um sistema (ou um agente de IA) confirmar canal padrão, escopos e cota restante numa única chamada, em vez de descobrir por tentativa e erro.

curl https://sua-empresa.konversia.com.br/api/v1/me \
  -H "Authorization: Bearer $KONVERSIA_API_KEY"

{
  "company": { "id": 42, "name": "Loja Exemplo" },
  "subscription": { "active": true, "status": "active" },
  "scopes": ["messages:send", "messages:read", "files:write"],
  "default_channel_id": 7,
  "quota": { "used": 1230, "limit": 5000, "remaining": 3770 }
}

quota.limit vem 0 quando a empresa não tem teto (envio ilimitado); nesse caso quota.remaining vem null, em vez de um número negativo sem sentido.

Erros de autenticação e assinatura

Situação	Código	Status HTTP
Cabeçalho ausente, ou chave inválida/revogada	unauthenticated	401
Chave válida sem o escopo exigido pelo endpoint	forbidden_scope	403
Assinatura da empresa inativa, ou com pagamento pendente	subscription_inactive	403

Assinatura pendente não revoga a chave: assim que o pagamento é reconhecido, a API volta a responder sozinha, sem precisar gerar uma chave nova.

Relacionado

• Enviar mensagens
• Erros
• Chaves de API (guia do produto)