Introducción a la autenticación

Todas las credenciales viajan en la misma cabecera:

Authorization: Bearer <valor>

El esquema se compara respetando mayúsculas — bearer abc no entra.

Cuál te toca

Hay cuatro credenciales. Si estás integrando un sistema, la tuya es la primera y puedes saltarte el resto.

Credencial	Quién la usa	Qué abre
Token de máquina	Tu sistema	Documentos, numeración, certificados, software, webhooks, planes
Token de persona	El panel web	Lo mismo, pero atado a un usuario y su rol
Llave de aprovisionamiento	Nosotros	Solo dar de alta emisores
Llave de plataforma	Nosotros	Administración de la plataforma

Consejo

Para integrar solo necesitas el token de máquina: se obtiene con client_credentials y no caduca la sesión de nadie.

Token de máquina

Se obtiene en POST /v1/oauth/token con tu client_id y client_secret. Dura una hora.

El emisor sobre el que actúas va dentro del token: no se puede cambiar con una cabecera. Un client_id factura para un emisor y solo para ese.

El token no se revisa contra la base

Se comprueba la firma y la expiración, nada más. Si revocas una credencial, los tokens ya emitidos siguen sirviendo hasta que venzan —hasta una hora—. Para un corte inmediato, avísanos.

Token de persona

Sale de POST /v1/auth/login. Tiene dos roles:

• CLIENTE — atado a un emisor, fijo. No puede cambiar de emisor.
• ADMIN — elige sobre qué emisor trabaja con la cabecera X-Company-Id. Si la ruta la necesita y falta, responde 400 diciendo exactamente eso.

Rutas sin autenticación

Cuatro cosas no piden credencial:

• POST /v1/oauth/token — pedir el token
• POST /v1/auth/login, /refresh, /logout, /password/forgot, /password/reset
• GET /v1/catalogs/* — las tablas DIAN son públicas
• GET /health

Qué pasa si algo va mal

Todos los errores tienen la misma forma:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API key inválida o ausente",
  "errors": []
}

Situación	Código	code	Mensaje
Sin cabecera, o sin Bearer	401	UNAUTHORIZED	API key inválida o ausente
Firma inválida o token vencido	401	UNAUTHORIZED	Token inválido o expirado
Token de máquina en ruta de plataforma	403	FORBIDDEN	Las credenciales de integración no administran la plataforma
Token de máquina en acción de persona	403	FORBIDDEN	Esta acción la hace una persona, no un sistema
Usuario ADMIN sin X-Company-Id	400	BAD_REQUEST	Falta indicar sobre qué emisor trabajar (cabecera X-Company-Id)

Límite de peticiones

300 por minuto y por IP, global. Por encima, 429.

Pedir un token en cada llamada es la forma más rápida de llegar a ese límite: guárdalo y reúsalo mientras viva.