Autenticación con API Key
Referencia tecnica del endpoint Autenticación con API Key.
Descripcion
Las API keys de empresa permiten autenticar requests directamente contra la API sin necesidad de hacer login previo ni gestionar tokens JWT con expiración.
Cada key está asociada a una empresa específica. No requiere idEmpresa en el body — el sistema lo deriva automáticamente de la key.
Formas de enviar la API key
El middleware acepta la key en dos headers alternativos. Usar cualquiera de los dos es equivalente:
Opción 1: X-API-Key (recomendada)
X-API-Key: bt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Opción 2: Authorization Bearer
Authorization: Bearer bt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
El sistema detecta automáticamente que es una API key y no un JWT porque la clave empieza con bt_live_ o bt_test_.
Prefijos de clave
| Prefijo | Ambiente |
|---|---|
bt_live_ | Producción |
bt_test_ | Sandbox / testing |
Producción y Sandbox son ambientes independientes: no comparten datos, empresas ni CFEs.
Cómo obtener una API key
Desde la interfaz web
- Ingresar a Mi cuenta → API
- En la sección API keys de empresa, hacer clic en Nueva API key
- Asignar un nombre descriptivo (ej.
Integrador POS principal) - Guardar la clave completa inmediatamente — no vuelve a mostrarse
Desde la API (requiere JWT)
curl -X POST '$BASE/api/v1/apikeys' \
-H 'Authorization: Bearer <JWT>' \
-H 'Content-Type: application/json' \
-d '{
"nombre": "Integrador POS principal",
"descripcion": "Canal de emision productivo"
}'
La respuesta incluye el campo ApiKey con la clave completa. Guardarla en ese momento — el sistema almacena solo el hash.
Ver: Crear API key
idEmpresa con API key
Cuando se usa una API key, no es necesario enviar idEmpresa en el body de los endpoints que lo aceptan. La empresa se resuelve automáticamente desde la key.
Si se envía igualmente, debe coincidir con la empresa de la key. Enviar una empresa diferente resulta en HTTP 403.
Rate limiting
Cada API key puede tener límites configurados de requests por minuto y por hora. Cuando se supera el límite:
- HTTP
429 Too Many Requests - Headers de respuesta:
Retry-After,X-RateLimit-Limit-Minute,X-RateLimit-Remaining-Minute,X-RateLimit-Limit-Hour,X-RateLimit-Remaining-Hour
Errores de autenticación
| HTTP | Causa |
|---|---|
401 | Key inválida, revocada o no encontrada |
403 | Key válida pero sin acceso al recurso solicitado |
429 | Límite de rate limit superado |
Comparación con JWT
| Aspecto | JWT | API Key |
|---|---|---|
| Obtención | POST /api/auth/login + renovar cada 6 horas | Crear una vez, usar indefinidamente |
| Header | Authorization: Bearer <token> | X-API-Key: bt_live_... o Authorization: Bearer bt_live_... |
| Empresa | Requiere idEmpresa en el body o en sesión | Derivada automáticamente de la key |
| Expiración | 6 horas (renovable con refresh token) | No expira (hasta revocación) |
| Revocación | POST /api/auth/revoke | POST /api/v1/apikeys/{id}/revocar |
| Rate limit | Sin límite por defecto | Configurable por key |
| Recomendado para | Usuarios interactivos | Integraciones automatizadas |