Autenticación

Cómo crear una API key en Configuración → Desarrolladores → API Keys, qué permisos (scopes) darle, cuándo expira, cómo revocarla y cómo probarla.

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.

Clic en «Nueva API key», se escribe el nombre, se eligen Permisos especificos y 90 días, y el cursor queda sobre «Crear API key»

  1. Abre Configuración (el engrane de arriba a la derecha, o tu menú de usuario → Configuración).

  2. En el menú de la izquierda, en Desarrolladores, entra a API Keys.

    El engrane de arriba a la derecha abre Configuración (1); en Desarrolladores está API Keys (2)

  3. Haz clic en Nueva API key (si todavía no tienes ninguna, el botón dice Crear mi primera API key).

  4. Escribe un Nombre que diga dónde la vas a usar, por ejemplo "Integración n8n".

  5. En Permisos deja Acceso completo o elige Permisos especificos y marca solo los que necesita tu integración (tabla de abajo).

  6. En Expiracion elige Nunca expira, 30 dias, 90 dias o 1 año.

  7. Haz clic en Crear API key.

    Diálogo Nueva API key: nombre (4), Permisos especificos con dos permisos marcados (5), expiración de 90 días (6) y el botón Crear API key (7)

  8. 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 panelScopePermite
Contactos - lecturacontacts:readListar y consultar contactos
Contactos - escrituracontacts:writeCrear y actualizar contactos (incluye la lectura)
Conversaciones - lecturaconversations:readListar conversaciones y leer sus mensajes
Conversaciones - escrituraconversations:writeAbrir conversaciones y cambiar su estado (incluye la lectura)
Mensajes - enviomessages:sendEnviar mensajes de texto y archivos
Mensajes - plantillasmessages:send_templateListar y enviar plantillas de WhatsApp
Agente IAbot:manageEncender o pausar al agente en una conversación
Webhookswebhooks:manageDar 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

HTTPCódigoMotivo
401MISSING_API_KEYFalta el header Authorization: Bearer ...
401INVALID_API_KEYEl token no existe, fue revocado o ya expiró
403MODULE_NOT_ENABLEDTu plan no incluye la API
403INSUFFICIENT_SCOPELa 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.