Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ryvo-3dab4d1a.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Formato del header

Authorization: Bearer ryvo_live_abc123def456...

​
Crear una API key

  1. Entra a 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>
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.

​
Revocar una API key

Si una key se filtra (ej. la commiteaste a un repo público), entra a 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

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.
Carga el token desde process.env.RYVO_API_KEY o equivalente. Nunca lo escribas directo en el código fuente.
Las API keys solo deben usarse desde tu servidor. Si las expones al frontend (browser, mobile app), cualquier usuario puede leerlas con DevTools.
Cada 90 días, crea una nueva key, actualiza la integración, y revoca la vieja. Si ya hubo un incidente sospechoso, rota inmediato.

​
Verificar que tu key funciona

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

StatuserrorSignifica
401unauthorizedHeader faltante, mal formado, key inválida o revocada.
429rate_limit_exceededDemasiadas peticiones. Lee Rate Limits.