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 conkellu_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:
- Crea una clave nueva con los mismos permisos.
- Despliega la clave nueva en tu sistema.
- 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ímite | Valor |
|---|---|
| Por clave | 120 peticiones por minuto |
| Por dirección IP | 300 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ó.