Skip to main content
Cada escopo é uma porta na sua chave: app, usuário, conversa ou mensagem — abra só o necessário.
O JWT do usuário não usa esses escopos. Ele autentica o app do cliente em /v1/chat/* (REST) e no WebSocket. A API Key é para o seu backend.

​
Como enviar a chave

Recomendado
Alternativo
A API Key pertence a um workspace. Você não acessa outro workspace com a mesma chave. Não envie x-workspace-id na v1.

​
Combinações comuns

Setup do app

chat:apps:create, chat:apps:manage, chat:apps:list

Identidade

chat:users

Conversas no backend

chat:conversations:read, chat:conversations:write

Mensagens

chat:messages:send, chat:messages:read
Lista de escopos vazia na criação = acesso ADMIN. Em produção, restrinja sempre.

​
Escopos disponíveis

Listar e consultar Chat Apps do workspace.
Criar Chat App (POST /v1/chat/apps). A resposta inclui o signing secret.
Atualizar nome, origens, flags JWT e rotacionar o secret.
Remover Chat App (soft delete).
Upsert de usuários, emissão de JWT e vínculo de agentes da equipe.
Listar e obter conversas do workspace.
Criar conversa, membros, papéis, join e exclusão lógica.
Enviar mensagem (1 crédito CHAT_MESSAGE por envio).
Listar mensagens e marcar leitura.
Apagar mensagem (soft delete).

​
JWT vs API Key

​
Erros comuns

Confira Authorization: Bearer sk_... ou o JWT (iss = notifique-chat, aud = Chat App). Token revogado ou secret rotacionado → CHAT_INVALID_TOKEN.
Escopo ausente na chave, origem fora de allowedOrigins, ou JWT tentando criar conversa com flags desligadas (CHAT_CLIENT_CREATE_DISABLED).
Workspace bloqueado (WORKSPACE_BLOCKED), créditos insuficientes (INSUFFICIENT_CREDITS) ou limite de gasto da chave.
CHAT_DIRECT_EXISTS — o par de usuários já tem DIRECT. Use o id retornado na listagem.

​
Próximos passos