Todas las peticiones a la API llevan tu API key en el header Authorization:
Authorization: Bearer yol_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Una API key empieza con yol_ y es una credencial de la empresa: ve todos los contactos y conversaciones de la cuenta, sin importar quién la creó.
Crear una API key
Solo el dueño o un administrador de la cuenta pueden crear y revocar API keys, y solo en los planes que incluyen la API: Escala y Enterprise (y Corporativo, si ya lo tienes contratado), o si el equipo de Yolani la activó en tu cuenta.
-
Abre Configuración (el engrane de arriba a la derecha, o tu menú de usuario → Configuración).
-
En el menú de la izquierda, en Desarrolladores, entra a API Keys.
-
Haz clic en Nueva API key (si todavía no tienes ninguna, el botón dice Crear mi primera API key).
-
Escribe un Nombre que diga dónde la vas a usar, por ejemplo "Integración n8n".
-
En Permisos deja Acceso completo o elige Permisos especificos y marca solo los que necesita tu integración (tabla de abajo).
-
En Expiracion elige Nunca expira, 30 dias, 90 dias o 1 año.
-
Haz clic en Crear API key.
-
Copia el token con Copiar y guárdalo en un lugar seguro. Luego Listo, la guarde.
También puedes crearla desde Canales: en el grupo Para desarrolladores, la fila API de Yolani tiene los botones Nueva API key y Administrar API keys. Ese grupo solo aparece si tu plan incluye la API.
El token se muestra una sola vez:
Yolani guarda solo una huella del token, no el token. Si lo pierdes, revoca esa key y crea otra. No lo publiques en un repositorio ni lo pongas en el código de una página web o una app: cualquiera que lo vea puede leer y escribir en tu cuenta.
¿No ves API Keys?:
Si en Configuración no aparece Desarrolladores → API Keys, o al abrirla ves "API publica no está activo", tu plan no incluye la API o no eres dueño ni administrador de la cuenta. Desde la entrada de una agencia tampoco se pueden crear API keys: se las tiene que crear el dueño de la cuenta.
Permisos (scopes)
Acceso completo permite todo. Con Permisos especificos eliges entre estos:
| En el panel | Scope | Permite |
|---|---|---|
| Contactos - lectura | contacts:read | Listar y consultar contactos |
| Contactos - escritura | contacts:write | Crear y actualizar contactos (incluye la lectura) |
| Conversaciones - lectura | conversations:read | Listar conversaciones y leer sus mensajes |
| Conversaciones - escritura | conversations:write | Abrir conversaciones y cambiar su estado (incluye la lectura) |
| Mensajes - envio | messages:send | Enviar mensajes de texto y archivos |
| Mensajes - plantillas | messages:send_template | Listar y enviar plantillas de WhatsApp |
| Agente IA | bot:manage | Encender o pausar al agente en una conversación |
| Webhooks | webhooks:manage | Dar de alta y de baja webhooks desde la API. Ver Webhooks |
GET /api/v1/me y GET /api/v1/webhooks/event-types funcionan con cualquier key válida. Si a una key le falta el permiso de un endpoint, la API responde 403 con el código INSUFFICIENT_SCOPE.
Para conectar Claude, Cursor u otra app de IA con una API key en vez de entrar con tu usuario, la key tiene que ser de Acceso completo: una con Permisos especificos no abre el conector.
Verificar tu API key
/me sirve para probar que la key funciona y ver qué permisos tiene:
curl https://api.yolani.co/api/v1/me \
-H "Authorization: Bearer yol_TU_TOKEN"
Respuesta:
{
"success": true,
"data": {
"company": { "id": 12, "name": "Mi Empresa" },
"api_key": {
"name": "Integración n8n",
"prefix": "yol_abcdefgh",
"scopes": ["messages:send", "conversations:read"]
}
}
}
Una key con Acceso completo devuelve "scopes": ["write"].
Errores de autenticación
| HTTP | Código | Motivo |
|---|---|---|
| 401 | MISSING_API_KEY | Falta el header Authorization: Bearer ... |
| 401 | INVALID_API_KEY | El token no existe, fue revocado o ya expiró |
| 403 | MODULE_NOT_ENABLED | Tu plan no incluye la API |
| 403 | INSUFFICIENT_SCOPE | La key no tiene el permiso que pide ese endpoint |
Revocar una key
En Configuración → Desarrolladores → API Keys, abre el menú ⋯ de la key, elige Revocar y confirma con Revocar. Deja de funcionar al instante y no se puede deshacer.
En la misma tabla ves de cada key su nombre, el inicio del token (yol_abcdefgh...), sus permisos, cuándo se creó, su último uso y su estado: Activa, Expirada o Revocada. La columna de último uso te dice si una integración vieja sigue llamando a la API antes de revocar su key.
Una buena práctica es crear una key por integración (una para n8n, otra para tu ERP): si una se filtra, revocas solo esa.


