API Keys
Las API Keys permiten que aplicaciones externas consuman nuestra API sin utilizar credenciales personales de usuarios. Cada clave está asociada a un tenant y tiene permisos controlados.
¿Cuándo usar una API Key?
- Integraciones servidor-a-servidor (webhooks, scripts automatizados, pipelines)
- Aplicaciones de terceros que necesitan acceso programático
- Cuando no quieres compartir credenciales de un usuario real
Tipos de clave
| Tipo | Prefijo | Header | Entorno | Uso |
|---|---|---|---|---|
| Secreta | sk_ | X-API-Key | Servidor | Automatización, integraciones backend — autorización por privilegio + operaciones, no por el rol de la clave |
| Publicable | pk_ | X-Publishable-Key | Navegador | SDK browser — lectura limitada, billing checkout/portal, notificaciones (con JWT) |
Las claves secretas nunca deben exponerse en aplicaciones web o móviles.
El panel de API Keys del frontend permite elegir el tipo de clave (
secret/publishable) directamente al crearla, con una breve explicación de cada uso en el propio formulario.
Seguridad
Las claves se almacenan con hash SHA-256. El valor completo se muestra únicamente en el momento de la creación y no puede recuperarse después.
Formatos:
- Secreta:
sk_{64 caracteres hex}— 67 caracteres en total - Publicable:
pk_{64 caracteres hex}— 67 caracteres en total
Permisos
Cada clave es super o normal (privilegio de esa empresa, no de la plataforma). Las normales declaran una lista de operaciones (área:verbo, por ejemplo users:read); la lista puede estar vacía. El privilegio y las operaciones no se editan in-place: solo una rotación (emite un secreto nuevo) puede cambiarlos. Solo un OWNER/ADMIN con sesión humana puede crear, conservar, revocar o eliminar una clave super. Una clave API no puede mintar ni alterar supers.
Firewall en cada petición: si te autenticas con sk_ o pk_, el acceso lo decide el privilegio y las operaciones concedidas, no el rol de compañía guardado en la clave.
| Privilegio | Qué puede hacer |
|---|---|
| Super secreta | Todas las operaciones del catálogo de esa empresa |
| Super publicable | Solo el techo pk_ ya acordado (no invitaciones, no escrituras fuera de ese techo) |
| Normal | Solo las operaciones de su lista; lista vacía = autentica y deniega todo el catálogo |
Una sesión JWT de usuario no entra en este firewall: siguen los permisos de persona. Clave inexistente o revocada → 401 con mensaje genérico (Invalid API key / Invalid publishable key). Clave caducada → 401 con mensaje distinto (API key has expired), para poder distinguir el motivo. Clave válida sin la operación → 403 (Insufficient authorization for this operation).
La analítica de clicks de UI (stats y project IDs) se concede con event-logger:read / event-logger:write sobre /event-logger/*. No existe un área de catálogo analytics ni rutas bajo /analytics — ver Event logger.
El rol de la clave (owner / admin / member / viewer) se sigue guardando y puede usarse en reglas de negocio concretas (por ejemplo, quién puede asignar OWNER), pero ya no es el mecanismo que abre o cierra la API para esa clave.
Adicionalmente, puedes especificar scopes (histórico) y opcionalmente una descripción libre (máx. 500 caracteres) para documentar el propósito de la clave.
Endpoints
Los endpoints de gestión de claves requieren autenticación. Las peticiones de gestión pueden usar JWT o una clave secreta (X-API-Key: sk_…). Crear/listar/rotar/revocar/eliminar con sk_ exige la operación api-keys:read o api-keys:write según el método. Mintar o alterar una clave super sigue exigiendo JWT humano OWNER/ADMIN. Las peticiones a otros módulos con sk_/pk_ se autorizan por el firewall de operaciones, no por el rol de la clave.
Crear una API Key
POST /api-keys
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"name": "Mi integración",
"keyType": "secret",
"privilege": "super",
"role": "member",
"scopes": ["users:read"],
"description": "Usada por la integración de facturación", // opcional, máx. 500 caracteres
"expiresAt": "2027-01-01T00:00:00Z" // opcional
}Para una clave publicable (SDK browser), usa "keyType": "publishable". La respuesta incluirá un prefijo pk_ en lugar de sk_.
Respuesta (201):
{
"id": "uuid",
"name": "Mi integración",
"keyPrefix": "sk_a1b2c3",
"key": "sk_abc123...",
"privilege": "super",
"operations": null,
"role": "member",
"scopes": ["users:read"],
"description": "Usada por la integración de facturación",
"expiresAt": null,
"createdAt": "2026-01-01T10:00:00Z"
}El campo
keysolo aparece en esta respuesta. Guárdalo en un lugar seguro.
privilege es obligatorio (super o normal). Si es normal, hay que enviar operations (array, puede estar vacío). Una publicable no puede recibir operaciones fuera del techo pk_ (p. ej. invitations:write). Requiere rol OWNER o ADMIN; mintar o conservar una super solo con sesión humana.
Gate de plan: si el tenant tiene una suscripción activa cuyo plan no declara el feature de catálogo api_access (ver Facturación → Catálogo), la creación se rechaza con 403 Forbidden. Un tenant sin ninguna suscripción activa no se ve afectado — es el mismo comportamiento agnóstico de billing que ya aplican max_companies y max_users (ver Empresas).
Si el tenant tiene un plan de reventa asignado (ver Planes de reventa, ), ese plan gobierna en su lugar: concede acceso si declara api_access en
features, lo bloquea si no lo declara (aunque el tenant no tenga ninguna suscripción de plataforma). Sin plan de reventa asignado, se aplica el gate de plan de plataforma descrito arriba sin cambios.
Listar API Keys
GET /api-keys?page=1&limit=20
Authorization: Bearer <token>
X-Company-Id: <companyId>Devuelve las claves del tenant activo. Incluye privilege y operations. Nunca incluye el valor completo de la clave.
Paginación — page (default 1) y limit (default 20, máximo 100) son opcionales. La respuesta es un envelope { data, total, page, limit }, no un array plano. Una página fuera de rango no es un error: devuelve data: [] con total reflejando el conteo real.
Obtener una API Key
GET /api-keys/:id
Authorization: Bearer <token>
X-Company-Id: <companyId>Revocar una API Key
POST /api-keys/:id/revoke
Authorization: Bearer <token>
X-Company-Id: <companyId>Devuelve la clave actualizada (200). La clave queda inutilizable inmediatamente, pero no se elimina — sigue apareciendo en el listado como revocada (trazabilidad). Requiere rol OWNER o ADMIN.
Eliminar una API Key permanentemente
DELETE /api-keys/:id
Authorization: Bearer <token>
X-Company-Id: <companyId>Devuelve 204. Borra la clave de la base de datos de forma permanente e irreversible — a diferencia de revocar, deja de aparecer en el listado. Puedes eliminar una clave esté activa o ya revocada. Requiere rol OWNER o ADMIN.
Rotar una API Key
POST /api-keys/:id/rotate
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"privilege": "normal",
"operations": ["users:read"]
}Revoca la clave actual y crea una nueva (secreto nuevo). El body es opcional: si omites privilege u operations, se conservan los anteriores. Devuelve la nueva clave completa (igual que en la creación). Rotar una super (o convertir a super) solo lo puede hacer un OWNER/ADMIN humano. Si la clave ya está revocada → 409; no se emite una clave nueva.
Usar una clave secreta en tus peticiones
Envía la clave en el header X-API-Key:
GET /users
X-API-Key: sk_abc123def456...
X-Company-Id: <companyId>Usar una clave publicable (SDK browser)
Envía la clave en el header X-Publishable-Key:
GET /users
X-Publishable-Key: pk_abc123def456...
X-Company-Id: <companyId>Las claves publicables están restringidas a un subconjunto de endpoints (lectura en users/companies/settings, billing checkout/portal, etc.). Operaciones de administración o escritura devuelven 403.
Notificaciones con clave publicable
Los endpoints de notificaciones requieren doble autenticación: la clave publicable (X-Publishable-Key) y un JWT de usuario activo (Authorization: Bearer).
GET /notifications
X-Publishable-Key: pk_abc123...
Authorization: Bearer <jwt>Ciclo de vida
Creación → Activa
Rotación → Clave vieja revocada + nueva clave creada
Revocación → Inutilizable inmediatamente (la clave se conserva, marcada como revocada)
Expiración → Rechazada automáticamente cuando expiresAt < ahora
Eliminación → Borrado permanente de la base de datos (acción explícita y separada)Las claves revocadas o expiradas no se eliminan automáticamente de la base de datos (conservan la trazabilidad) — eliminarlas requiere la acción explícita DELETE /api-keys/:id.
Multi-tenancy
Una API Key pertenece a un único tenant. Es imposible utilizar la clave de un tenant para acceder a los datos de otro.
Auditoría
Las operaciones importantes generan eventos de dominio:
api-key.created— al crear una clave (incluyeprivilegeyoperations)api-key.revoked— al revocar una claveapi-key.rotated— al rotar una clave (incluyeprivilegeyoperationsresultantes)api-key.deleted— al eliminar una clave permanentemente
El uso frecuente (cada petición) actualiza únicamente el campo lastUsedAt de la clave, sin generar un evento por petición.