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

# Autenticación

> Bearer tokens con API keys que tú creas y revocas desde el portal.

Todas las peticiones a la API de Ryvo requieren autenticación con un **Bearer token**. Los tokens se llaman **API keys** y los gestionas desde [app.ryvo.so/developers](https://app.ryvo.so/developers).

## Formato del header

```http theme={null}
Authorization: Bearer ryvo_live_abc123def456...
```

## Crear una API key

1. Entra a [app.ryvo.so/developers](https://app.ryvo.so/developers).
2. Click en **Nueva API key**.
3. Ponle un nombre descriptivo (ej. `n8n producción`, `mi-crm-staging`).
4. Copia el token completo. **Solo se muestra una vez** — guárdalo en un secret manager.

El token tiene este formato:

```
ryvo_live_<64 caracteres hexadecimales>
```

<Warning>
  Después de cerrar el modal de creación, no podemos volver a mostrarte el token. Si lo pierdes, revoca esa key y crea una nueva.
</Warning>

## Revocar una API key

Si una key se filtra (ej. la commiteaste a un repo público), entra a [app.ryvo.so/developers](https://app.ryvo.so/developers), encuentra la key en la lista y click en **Revocar**.

A partir de ese momento, cualquier petición con esa key devuelve `401 unauthorized`. La acción es inmediata e irreversible — no hay periodo de gracia.

## Cómo guardamos las keys

* **Nunca almacenamos el token en claro.** Solo guardamos un hash con HMAC-SHA-256 + un *pepper* server-side.
* En el portal verás solo el prefijo (`ryvo_live_abc123…`) y el último uso.
* Aunque alguien obtenga acceso a nuestra base de datos, las keys siguen siendo seguras: el pepper vive solo en variables de entorno y el hash no es reversible.

## Buenas prácticas

<AccordionGroup>
  <Accordion title="Una key por entorno y por integración" icon="key">
    Crea una key separada para cada CRM, n8n workflow o entorno (staging vs producción). Si una se compromete, revocas solo esa sin afectar al resto.
  </Accordion>

  <Accordion title="Variables de entorno, nunca código" icon="lock">
    Carga el token desde `process.env.RYVO_API_KEY` o equivalente. Nunca lo escribas directo en el código fuente.
  </Accordion>

  <Accordion title="Server-side only" icon="server">
    Las API keys solo deben usarse desde tu servidor. Si las expones al frontend (browser, mobile app), cualquier usuario puede leerlas con DevTools.
  </Accordion>

  <Accordion title="Rota periódicamente" icon="rotate">
    Cada 90 días, crea una nueva key, actualiza la integración, y revoca la vieja. Si ya hubo un incidente sospechoso, rota inmediato.
  </Accordion>
</AccordionGroup>

## Verificar que tu key funciona

```bash theme={null}
curl -i -X POST https://api.ryvo.so/v1/calls \
  -H "Authorization: Bearer ryvo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"invalid","to":"+5215555550100"}'
```

* Si la key es válida pero el `agent_id` no, vas a recibir `403 agent_not_found`.
* Si la key está mal o revocada, recibes `401 unauthorized`.
* Si recibes `401`, revisa que el header esté bien escrito (`Bearer ` con espacio) y que la key no esté revocada en el portal.

## Errores de autenticación

| Status | `error`               | Significa                                               |
| ------ | --------------------- | ------------------------------------------------------- |
| `401`  | `unauthorized`        | Header faltante, mal formado, key inválida o revocada.  |
| `429`  | `rate_limit_exceeded` | Demasiadas peticiones. Lee [Rate Limits](/rate-limits). |