Autenticación
API keys, permisos por alcance y manejo seguro de credenciales.
API keys
La API se autentica con una API key enviada como token Bearer en el encabezado Authorization. No usa OAuth ni sesiones.
Encabezado de autenticación
Authorization: Bearer dd_test_…
El prefijo indica el ambiente:
| Prefijo | Ambiente | Uso |
|---|---|---|
dd_test_ | Pruebas | Desarrollo e integración. No genera comprobantes con validez fiscal. |
dd_live_ | Producción | Emisión real. Disponible cuando la plataforma complete su acreditación. |
Permisos por alcance
Cada API key tiene una lista de permisos (scopes). Una operación responde 403 forbidden si la clave no tiene el permiso requerido. Asigna a cada clave solo lo que necesita.
| Permiso | Permite |
|---|---|
companies:read | Consultar empresas emisoras. |
companies:write | Crear, modificar y eliminar empresas emisoras. |
documents:read | Consultar comprobantes, estados, eventos, XML y PDF. |
documents:write | Emitir comprobantes. |
received:write | Responder comercialmente a comprobantes recibidos. |
webhooks:manage | Administrar endpoints de webhooks y sus entregas. |
Crear, rotar y revocar claves
Las claves se administran desde el portal. Por seguridad, esas acciones exigen verificación en dos pasos (MFA) y haber confirmado tu identidad en los últimos 10 minutos.
- Rotar una clave genera una nueva para reemplazarla. Hazlo de forma periódica y siempre que sospeches de una exposición.
- Revocar una clave la invalida de inmediato: las solicitudes que la usen responderán
401.
Buenas prácticas
- Usa la API solo desde tu backend. Una clave incluida en una aplicación móvil o en JavaScript del navegador queda expuesta.
- Guarda las claves en un gestor de secretos o en variables de entorno, nunca en el repositorio.
- Usa claves distintas por aplicación y por ambiente, para poder revocar una sin afectar a las demás.
- No compartas claves por correo ni por tickets de soporte.
Errores de autenticación
| Estado | Código | Causa |
|---|---|---|
| 401 | unauthenticated | Falta la clave, tiene un formato incorrecto o fue revocada. |
| 403 | forbidden | La clave es válida pero no tiene el permiso que exige la operación. |
¿Algo no está claro o falta en esta página? Escríbenos por el centro de soporte.