Skip to main content

​
Pré-requisitos

  • Acesso ao dashboard do workspace (onde as API Keys são criadas e gerenciadas).
  • Uma API Key criada no dashboard.

​
1. Onde criar e gerenciar API Keys

As API Keys não são criadas via API pública. Elas são criadas e revogadas no dashboard do workspace:
  1. Acesse o dashboard e selecione o workspace.
  2. Vá em API Keys.
  3. Crie uma nova chave: defina nome, escopos (opcional) e, se desejar, restrições por instâncias WhatsApp, domínios de e-mail e apps de push.
  4. Copie a chave no momento da criação — ela não será exibida novamente por completo (apenas prefixo nas listagens).
Cada chave está vinculada a um workspace. Chaves com escopos vazios têm acesso a todas as operações permitidas pelo plano; caso contrário, apenas as operações dos escopos selecionados. As listas instanceIds, domainIds e pushAppIds (quando vazias) permitem acesso a todos os recursos do tipo; quando preenchidas, limitam a chave àqueles itens.

​
2. Como enviar a API Key na requisição

Em toda requisição à API v1, envie a API Key em um dos formatos: Opção A — Header Authorization (Bearer) 
Authorization: Bearer sk_live_xxxxx
Opção B — Header x-api-key 
x-api-key: sk_live_xxxxx
Exemplo completo: 
POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
ou 
POST /v1/whatsapp/messages
Content-Type: application/json
x-api-key: sk_live_xxxxx

​
3. Respostas de erro comuns

StatusSituação
401API Key ausente, inválida, revogada ou expirada.
402Plano do workspace expirado ou suspenso.
403Escopo insuficiente para a rota chamada; ou recurso não permitido para esta API Key (instância WhatsApp, domínio de e-mail ou app de push). Códigos: DOMAIN_NOT_ALLOWED, PUSH_APP_NOT_ALLOWED.

​
4. Escopos (resumo)

Ao criar a API Key no dashboard, você pode restringir por escopos. Exemplos:
  • WhatsApp: whatsapp:send, whatsapp:read, whatsapp:instances:list, whatsapp:instances:create, etc.
  • SMS: sms:send, sms:read, sms:cancel
  • E-mail: email:send, email:read, email:domains:list, email:domains:create, etc.
  • Push: push:send, push:read, push:devices:register, push:apps:read, push:apps:manage
  • Webhooks: webhooks:read, webhooks:manage
  • Logs: logs:read
  • Workspaces: workspace:read, workspace:create, workspace:update, workspace:delete

​
5. Restrições por recurso

No dashboard, além dos escopos, você pode limitar em quais recursos a chave atua:
CampoCanalEfeito
instanceIdsWhatsAppChave só pode usar as instâncias listadas. Lista vazia = todas.
domainIdsE-mailChave só pode enviar de remetentes cujo domínio está na lista. Lista vazia = todos os domínios verificados.
pushAppIdsPushChave só pode enviar para dispositivos dos apps listados. Lista vazia = todos os apps.
Se a requisição usar um recurso não permitido (ex.: enviar e-mail de um domínio não listado em domainIds), a API retorna 403 com code: DOMAIN_NOT_ALLOWED ou code: PUSH_APP_NOT_ALLOWED conforme o caso.

​
Resumo do fluxo

  1. Criar API Key no dashboard do workspace (Menu lateral → API Keys).
  2. Copiar a chave e guardá-la em local seguro (variável de ambiente, secrets).
  3. Em toda requisição à API v1: enviar Authorization: Bearer sk_live_xxxxx ou x-api-key: sk_live_xxxxx.
  4. (Opcional) Restringir escopos ou recursos (instâncias WhatsApp, domínios de e-mail, apps de push) no dashboard para limitar o que a chave pode fazer.