Autenticación

Cada petición a la API lleva una clave de tu negocio en el encabezado Authorization:

curl https://api.kellu.co/api/v1/me \
  -H "Authorization: Bearer kellu_sk_TU_CLAVE"
  • La clave empieza con kellu_sk_ y tiene 52 caracteres. Un token que no empieza con kellu_sk_ se rechaza sin consultarlo.
  • El negocio sale de la clave: ningún parámetro de la petición puede elegir otro negocio. Un id de otro negocio responde 404 not_found, igual que un id que no existe.
  • La sesión de la aplicación web no sirve: una cookie de sesión no autentica en /api/v1.

Quién crea las claves

El dueño del negocio o un usuario con perfil Administrador, en Configuración → API → Claves, una vez que el equipo de Kellu habilitó el acceso a la API para el negocio.

  • Máximo 10 claves activas por negocio (no revocadas ni vencidas).
  • La clave completa se muestra una sola vez, al crearla. Kellu guarda solo un hash y el prefijo (kellu_sk_ + 4 caracteres), que es lo que verás después en la lista.
  • Los permisos de una clave quedan fijos al crearla. Para cambiarlos, crea otra clave y revoca la anterior.

Vencimiento

Al crear la clave puedes dejarla sin vencimiento o darle una fecha futura. GET /me devuelve apiKey.expiresAt (ISO 8601 en UTC, null si no vence).

Una clave vencida o revocada responde 401 invalid_api_key, con el mismo mensaje que una clave inexistente: la respuesta no revela cuál de los casos es.

Rotación

No hay rotación automática. Para cambiar una clave sin cortar la integración:

  1. Crea una clave nueva con los mismos permisos.
  2. Despliega la clave nueva en tu sistema.
  3. Revoca la clave anterior en Configuración → API → Claves.

La lista de claves muestra el último uso de cada una (se actualiza como mucho una vez por minuto): úsalo para confirmar que la clave anterior ya no recibe tráfico antes de revocarla.

Límites de uso

LímiteValor
Por clave120 peticiones por minuto
Por dirección IP300 peticiones por minuto

Al superar un límite la API responde 429 rate_limited con el encabezado Retry-After (segundos) y error.details.retryAfterSeconds. Espera ese tiempo antes de reintentar. Detalle en Paginación y errores.

Acceso deshabilitado

Si el acceso a la API del negocio se deshabilita (o el negocio queda inactivo), toda clave vigente responde 403 api_access_disabled (una revocada o vencida sigue respondiendo 401). Las claves no se borran: vuelven a funcionar si el acceso se habilita de nuevo.

Buenas prácticas

  • Una clave por integración, con nombre claro: así puedes revocar una sin afectar a las demás.
  • Mínimo permiso: marca solo los permisos que la integración usa.
  • Nunca en el navegador ni en una app móvil: la clave da acceso a los datos de tu negocio. Úsala solo desde tu servidor.
  • Guárdala como secreto (variable de entorno o gestor de secretos), nunca en el repositorio.
  • Ponle vencimiento a las claves de pruebas o de integraciones temporales.
  • Revócala de inmediato si sospechas que se filtró.