Autenticación
Todos los endpoints de la Partner API requieren una Partner API Key — un secreto de larga duración con alcance a tu empresa logística.
Cómo funciona
Cada petición debe incluir la clave en el header HTTP X-Partner-API-Key:
GET /partner/api-keys HTTP/1.1
Host: api.digiantlabs.com
X-Partner-API-Key: dpk_live_abc123...
DigiAnt valida la clave y resuelve tu logistics_company_id a partir de ella automáticamente — no es necesario incluirlo en la URL ni en el cuerpo de la petición.
Gestión de claves API
Las claves API se gestionan desde la propia Partner API bajo /partner/api-keys. La creación inicial (bootstrap) requiere autenticación JWT del backoffice; el resto de operaciones usan la propia X-Partner-API-Key.
| Acción | Endpoint | Auth |
|---|---|---|
| Crear la primera clave | POST /partner/api-keys | JWT (backoffice) |
| Listar claves activas | GET /partner/api-keys | X-Partner-API-Key |
| Revocar una clave | DELETE /partner/api-keys/{id} | X-Partner-API-Key |
| Rotar claves | POST /partner/api-keys/{id}/rotate | X-Partner-API-Key |
El texto plano de la clave se muestra exactamente una vez al generarla. Guárdala inmediatamente en tu gestor de secretos. DigiAnt solo almacena un hash SHA-256 y no puede recuperar el texto plano posteriormente.
Formato de la clave
Las claves tienen el prefijo dpk_ para identificarlas fácilmente en logs y gestores de secretos. Ejemplo (acortado):
dpk_live_TFpq3vMNnWnuEkSR7bLsdEoGkJhH...
Rotar una clave
La rotación es una operación sin tiempo de inactividad:
- Llama a
POST /partner/api-keys/{id}/rotate - DigiAnt desactiva todas las claves existentes de tu empresa y emite una nueva
- Actualiza tu gestor de secretos con el nuevo texto plano antes de realizar la siguiente llamada a la API
Rota las claves de forma programada (p.ej., cada 90 días) o tras cualquier exposición sospechosa. Mantén la ventana de rotación corta: la clave antigua deja de funcionar en el momento en que se dispara la rotación.
Recomendaciones de seguridad
| Recomendación | Motivo |
|---|---|
| Almacena la clave en un gestor de secretos (AWS Secrets Manager, HashiCorp Vault, etc.) | Nunca incluyas claves en el código fuente |
| Usa HTTPS para todas las peticiones | Las claves enviadas por HTTP plano quedan expuestas en tránsito |
| Rota tras cualquier exposición | Revoca y regenera inmediatamente si una clave se filtra |
| Usa una clave por entorno | Mantén separadas las claves de staging y producción |
| Asigna nombres descriptivos | "Producción ERP — GOF" es más fácil de auditar que "clave 1" |
Respuestas de error
| Estado HTTP | Nombre del error | Significado |
|---|---|---|
401 Unauthorized | partner_api_key.not_found | Clave ausente, inválida o revocada |
401 Unauthorized | partner_api_key.expired | La clave existe pero expires_at ya ha pasado |