A API Key está sempre vinculada a um único Workspace. Todas as operações (criar instâncias, enviar mensagens) ocorrem dentro desse contexto. Você não consegue acessar dados de outro workspace com a mesma chave.
Tabela de Escopos (Permissões)
Ao criar uma API Key, você define o que ela pode fazer. Se você deixar a lista de escopos vazia, a chave terá acesso ADMIN (todas as operações permitidas). Para segurança, recomendamos restringir.Escopos por instâncias
whatsapp:instances:listVer instâncias e obter detalhes (QR Code).whatsapp:instances:createCriar novas conexões/instâncias.whatsapp:instances:disconnectDesconectar uma sessão ativa.whatsapp:instances:deleteRemover uma instância (apenas se desconectada).
Escopos por mensagens
whatsapp:sendEnviar mensagens (texto, mídia, arquivos).whatsapp:readConsultar status de envio/leitura.whatsapp:updateEditar o conteúdo de uma mensagem enviada.whatsapp:cancelCancelar uma mensagem agendada ou na fila.whatsapp:deleteApagar a mensagem para todos (Revoke).
Restrição por Instância
Além dos escopos (O QUE fazer), você pode limitar ONDE fazer. Se a sua API Key tiver o campoinstanceIds preenchido, ela só poderá interagir com aquelas instâncias específicas.
- Tentar enviar mensagem por uma instância não listada = Erro 403.
- Tentar listar instâncias = Retorna apenas as permitidas.
Respostas de Erro de Autenticação
Se algo der errado com sua chave, a API retorna códigos HTTP claros para facilitar o debug:| Status HTTP | O que aconteceu? | Como resolver? |
|---|---|---|
| 401 Unauthorized | API Key ausente, inválida, revogada ou expirada. | Verifique se o header está correto e se a chave não foi apagada no painel. |
| 403 Forbidden | Chave válida, mas sem permissão. | Verifique se a chave tem o Escopo necessário para a rota ou se a Instância está permitida. |
| 402 Payment Required | Plano do Workspace expirado ou suspenso. | O dono do Workspace precisa renovar a assinatura ou verificar os limites de mensagens. |