Skip to main content
A RyzeAPI usa dois tipos de token para autenticar cada requisição. Todos são enviados no header token. Entenda quando usar cada um e como tratar os erros mais comuns.

​
Dois tipos de token

TokenAccount

É o seu token principal. Com ele você cria e administra suas instâncias de WhatsApp.Escopo: sua conta inteira, todas as instâncias que ela possui.Quando usar: criar uma instância, listar todas as suas instâncias, deletar uma instância, ou qualquer operação em que você precise agir como “dono da conta”.

TokenInstance

Gerado automaticamente quando você cria uma instância nova. Cada instância tem o seu.Escopo: apenas aquela instância específica.Quando usar: operações do dia a dia, enviar mensagem, criar grupo, configurar webhook, ler contatos, etc. É o token que você vai usar em 99% das chamadas.
Como regra prática: use o TokenInstance sempre que o endpoint tem :instance no path. Use o TokenAccount apenas para criar/listar/deletar instâncias.

​
Ciclo de vida dos tokens

1

Você recebe seu TokenAccount

É entregue quando sua conta é criada. Guarde em local seguro, ele não pode ser recuperado depois.
2

Crie uma instância

Chame POST /api/instance/new enviando seu TokenAccount. A resposta traz o campo data.token, que é o TokenInstance daquela instância.
3

Use o TokenInstance no dia a dia

A partir daí, toda operação sobre aquela instância (mandar mensagem, ler contatos, configurar webhook) usa o TokenInstance.
4

Precisa criar outra instância?

Volte a usar seu TokenAccount para provisionar mais uma.

​
Três formas de enviar o token

Recomendamos sempre usar o header token. As outras formas existem apenas para casos específicos.

​
Header token (padrão recomendado)

​
Header Authorization: Bearer (compatibilidade)

Caso sua ferramenta só permita o padrão Bearer.

​
Query string ?token= (apenas WebSocket em navegador)

Usado quando não é possível enviar headers, o caso típico é WebSocket em JavaScript do browser, já que new WebSocket(...) não aceita headers customizados.
Query strings aparecem em logs de proxy e CDN. Não use em produção fora do caso WebSocket/browser.

​
Quem pode fazer o quê

  • Qualquer endpoint :instance da própria instância: enviar mensagem, ler contatos, configurar webhook, criar grupo, etc.
  • Inspecionar o estado atual da própria instância (GET /api/instance/list)
  • Abrir conexão WebSocket para receber eventos em tempo real
  • TokenInstance não cria instâncias novas, use TokenAccount para isso
  • TokenInstance de uma instância não opera outra instância, cada token só vale para a sua própria
  • TokenAccount/TokenInstance de uma conta não operam instâncias de outra conta

​
Proteção de acesso (ownership)

A RyzeAPI verifica automaticamente, antes de cada operação, se o token enviado tem permissão para aquele recurso específico. Isso impede que um token vaze acesso a instâncias de terceiros. Exemplos do que é bloqueado automaticamente:
  • Tentar enviar mensagem na instância B usando o token da instância A → 403
  • Tentar deletar uma instância que pertence a outra conta → 403
  • TokenAccount tentando criar mais instâncias do que sua cota permite → 403

​
Erros de autenticação

Todas respostas de erro de auth vêm com HTTP 401 (token inválido) ou 403 (sem permissão) e seguem o formato:

​
Mensagens que você pode encontrar

Se receber Invalid token sem saber por quê, verifique: (1) se o token está completo e sem espaços; (2) se está usando o tipo certo de token para aquele endpoint; (3) se a instância existe e está ativa.

​
Segurança: boas práticas

Trate todo token como credencial, armazene em variáveis de ambiente ou cofre de segredos, nunca no frontend ou em repositórios públicos.
Use um TokenInstance por instância, se um vazar, você revoga só aquele.
Use HTTPS em produção, a RyzeAPI aceita apenas conexões seguras.
Use o header token (não a query string) na maioria dos casos, headers não vão parar em logs de proxy.
Monitore o header X-RateLimit-Remaining para evitar ser bloqueado por excesso de requisições.

​
Próximo

Tipos de erro

Os formatos de resposta e como interpretar cada código HTTP.

Rate limit

Quanto você pode chamar por minuto e como reagir ao 429.