> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Como autenticar suas requisições com TokenAccount e TokenInstance

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

<CardGroup cols={2}>
  <Card title="TokenAccount" icon="users">
    É 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".
  </Card>

  <Card title="TokenInstance" icon="key">
    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**.
  </Card>
</CardGroup>

<Tip>
  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.
</Tip>

## Ciclo de vida dos tokens

<Steps>
  <Step title="Você recebe seu TokenAccount">
    É entregue quando sua conta é criada. Guarde em local seguro, ele não pode ser recuperado depois.
  </Step>

  <Step title="Crie uma instância">
    Chame [`POST /api/instance/new`](/pt/api/instance/create) enviando seu TokenAccount. A resposta traz o campo `data.token`, que é o **TokenInstance** daquela instância.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Precisa criar outra instância?">
    Volte a usar seu TokenAccount para provisionar mais uma.
  </Step>
</Steps>

## 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)

```http theme={null}
POST /api/message/text/$Instance_Name HTTP/1.1
Host: ryzeapi.cloud
Content-Type: application/json
token: seu-token-aqui

{"number": "5511999999999", "message": "Olá!"}
```

### Header `Authorization: Bearer` (compatibilidade)

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

```http theme={null}
Authorization: Bearer seu-token-aqui
```

### 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.

```javascript theme={null}
const ws = new WebSocket(
  `wss://ryzeapi.cloud/ws/$Instance_Name?token=${instanceToken}`
);
```

<Warning>
  Query strings aparecem em logs de proxy e CDN. **Não use em produção fora do caso WebSocket/browser.**
</Warning>

## Quem pode fazer o quê

<AccordionGroup>
  <Accordion title="Com TokenAccount" icon="users">
    * Criar novas instâncias ([`POST /api/instance/new`](/pt/api/instance/create))
    * Listar todas as suas instâncias ([`GET /api/instance/list`](/pt/api/instance/list))
    * Operar qualquer endpoint `:instance` das suas próprias instâncias (enviar mensagem, gerenciar grupos, etc.)
    * Deletar uma instância sua ([`DELETE /api/instance/delete/:instance`](/pt/api/instance/delete))
  </Accordion>

  <Accordion title="Com TokenInstance" icon="key">
    * 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`](/pt/api/instance/list))
    * Abrir conexão WebSocket para receber eventos em tempo real
  </Accordion>

  <Accordion title="Não permitido" icon="ban">
    * 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**
  </Accordion>
</AccordionGroup>

## 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:

```json theme={null}
{
  "success": false,
  "error": {
    "message": "descrição legível do problema"
  }
}
```

### Mensagens que você pode encontrar

| HTTP | Mensagem                                                            | Causa mais provável                                    |
| :--: | ------------------------------------------------------------------- | ------------------------------------------------------ |
|  401 | `Missing token in header`                                           | Você não enviou o header `token`                       |
|  401 | `Missing token in header, Authorization header, or query parameter` | Nenhuma das 3 formas de token foi usada                |
|  401 | `Invalid token`                                                     | Token não existe, está errado, ou foi revogado         |
|  401 | `Invalid instance token`                                            | O token não corresponde à instância no path            |
|  403 | `Instance token does not match requested instance`                  | Está usando o TokenInstance de A no path `:instance=B` |
|  403 | `Instance does not belong to your account`                          | TokenAccount tentando operar instância de outra conta  |
|  403 | `Account instance quota exceeded`                                   | Atingiu o limite de instâncias da sua conta            |

<Tip>
  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.
</Tip>

## Segurança: boas práticas

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

## Próximo

<CardGroup cols={2}>
  <Card title="Tipos de erro" icon="triangle-exclamation" href="/pt/guide/errors">
    Os formatos de resposta e como interpretar cada código HTTP.
  </Card>

  <Card title="Rate limit" icon="gauge" href="/pt/guide/rate-limit-cors">
    Quanto você pode chamar por minuto e como reagir ao `429`.
  </Card>
</CardGroup>