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

# Autenticación

> Cómo autenticar tus solicitudes con TokenAccount y TokenInstance

RyzeAPI utiliza dos tipos de token para autenticar cada solicitud. Ambos se envían en el header `token`. Comprende cuándo usar cada uno y cómo manejar los errores más comunes.

## Dos tipos de token

<CardGroup cols={2}>
  <Card title="TokenAccount" icon="users">
    Es tu **token principal**. Con él creas y administras tus instancias de WhatsApp.

    **Alcance:** toda tu cuenta, todas las instancias que posee.

    **Cuándo usarlo:** crear una instancia, listar todas tus instancias, eliminar una instancia, o cualquier operación en la que necesites actuar como "propietario de la cuenta".
  </Card>

  <Card title="TokenInstance" icon="key">
    Generado automáticamente cuando creas una nueva instancia. Cada instancia tiene el suyo propio.

    **Alcance:** **solo esa instancia específica**.

    **Cuándo usarlo:** operaciones del día a día, enviar un mensaje, crear un grupo, configurar un webhook, leer contactos, etc. Es el token que usarás en el **99% de las llamadas**.
  </Card>
</CardGroup>

<Tip>
  Como regla general: **usa el TokenInstance siempre que el endpoint tenga `:instance` en la ruta**. Usa el TokenAccount solo para crear/listar/eliminar instancias.
</Tip>

## Ciclo de vida del token

<Steps>
  <Step title="Recibes tu TokenAccount">
    Entregado al crearse tu cuenta. Guárdalo en un lugar seguro, no se puede recuperar después.
  </Step>

  <Step title="Crear una instancia">
    Llama a [`POST /api/instance/new`](/es/api/instance/create) enviando tu TokenAccount. La respuesta incluye el campo `data.token`, que es el **TokenInstance** de esa instancia.
  </Step>

  <Step title="Usa el TokenInstance día a día">
    A partir de ahí, cada operación sobre esa instancia (enviar un mensaje, leer contactos, configurar un webhook) usa el TokenInstance.
  </Step>

  <Step title="¿Necesitas crear otra instancia?">
    Vuelve a usar tu TokenAccount para aprovisionar una más.
  </Step>
</Steps>

## Tres formas de enviar el token

Recomendamos usar **siempre** el header `token`. Las otras formas existen solo para casos específicos.

### Header `token` (predeterminado recomendado)

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

{"number": "5511999999999", "message": "Hello!"}
```

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

En caso de que tu herramienta solo soporte el estándar Bearer.

```http theme={null}
Authorization: Bearer your-token-here
```

### Query string `?token=` (solo WebSocket en navegador)

Se usa cuando no es posible enviar headers, el caso típico es WebSocket en JavaScript de navegador, ya que `new WebSocket(...)` no acepta headers personalizados.

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

<Warning>
  Los query strings aparecen en los logs de proxies y CDNs. **No los uses en producción fuera del caso de WebSocket/navegador.**
</Warning>

## Quién puede hacer qué

<AccordionGroup>
  <Accordion title="Con TokenAccount" icon="users">
    * Crear nuevas instancias ([`POST /api/instance/new`](/es/api/instance/create))
    * Listar todas tus instancias ([`GET /api/instance/list`](/es/api/instance/list))
    * Operar cualquier endpoint `:instance` de tus propias instancias (enviar un mensaje, gestionar grupos, etc.)
    * Eliminar una de tus instancias ([`DELETE /api/instance/delete/:instance`](/es/api/instance/delete))
  </Accordion>

  <Accordion title="Con TokenInstance" icon="key">
    * Cualquier endpoint `:instance` de la **propia instancia**: enviar un mensaje, leer contactos, configurar un webhook, crear un grupo, etc.
    * Inspeccionar el estado actual de la propia instancia ([`GET /api/instance/list`](/es/api/instance/list))
    * Abrir una conexión WebSocket para recibir eventos en tiempo real
  </Accordion>

  <Accordion title="No permitido" icon="ban">
    * El TokenInstance **no crea nuevas instancias**, usa TokenAccount para eso
    * El TokenInstance de una instancia **no opera otra instancia**, cada token solo es válido para la suya propia
    * El TokenAccount/TokenInstance de una cuenta **no opera instancias de otra cuenta**
  </Accordion>
</AccordionGroup>

## Protección de acceso (ownership)

RyzeAPI verifica automáticamente, antes de cada operación, si el token enviado tiene permiso para ese recurso específico. Esto evita que un token filtre acceso a instancias de terceros.

Ejemplos de lo que se bloquea automáticamente:

* Intentar enviar un mensaje en la instancia `B` usando el token de la instancia `A` → `403`
* Intentar eliminar una instancia que pertenece a otra cuenta → `403`
* TokenAccount intentando crear más instancias de las que permite su cuota → `403`

## Errores de autenticación

Todas las respuestas de error de auth vienen con HTTP `401` (token inválido) o `403` (sin permiso) y siguen el formato:

```json theme={null}
{
  "success": false,
  "error": {
    "message": "human-readable description of the problem"
  }
}
```

### Mensajes que puedes encontrar

| HTTP | Mensaje                                                             | Causa más probable                                          |
| :--: | ------------------------------------------------------------------- | ----------------------------------------------------------- |
|  401 | `Missing token in header`                                           | No enviaste el header `token`                               |
|  401 | `Missing token in header, Authorization header, or query parameter` | No se usó ninguna de las 3 formas de token                  |
|  401 | `Invalid token`                                                     | El token no existe, es incorrecto o ha sido revocado        |
|  401 | `Invalid instance token`                                            | El token no coincide con la instancia en la ruta            |
|  403 | `Instance token does not match requested instance`                  | Estás usando el TokenInstance de A en la ruta `:instance=B` |
|  403 | `Instance does not belong to your account`                          | TokenAccount intentando operar una instancia de otra cuenta |
|  403 | `Account instance quota exceeded`                                   | Alcanzaste el límite de instancias de tu cuenta             |

<Tip>
  Si recibes `Invalid token` sin saber por qué, verifica: (1) que el token esté completo y sin espacios; (2) que estés usando el tipo de token correcto para ese endpoint; (3) que la instancia exista y esté activa.
</Tip>

## Seguridad: buenas prácticas

<Check>Trata **cada token** como una credencial, guárdalo en variables de entorno o en una bóveda de secretos, nunca en el frontend ni en repositorios públicos.</Check>
<Check>Usa un TokenInstance por instancia, si uno se filtra, solo revocas ese.</Check>
<Check>Usa HTTPS en producción, RyzeAPI solo acepta conexiones seguras.</Check>
<Check>Usa el header `token` (no el query string) en la mayoría de los casos, los headers no terminan en logs de proxies.</Check>
<Check>Monitorea el header `X-RateLimit-Remaining` para evitar ser bloqueado por exceso de solicitudes.</Check>

## Siguiente

<CardGroup cols={2}>
  <Card title="Tipos de error" icon="triangle-exclamation" href="/es/guide/errors">
    Los formatos de respuesta y cómo interpretar cada código HTTP.
  </Card>

  <Card title="Límite de velocidad" icon="gauge" href="/es/guide/rate-limit-cors">
    Cuánto puedes llamar por minuto y cómo reaccionar a `429`.
  </Card>
</CardGroup>