Autenticación · Documentación de la API

Todas las APIs de datos se autentican con una API key en la cabecera Authorization, con el esquema Bearer.

Envía tu API key en cada petición, en la cabecera Authorization con el esquema Bearer:

peticion.http

GET /v1/ruc/20131312955 HTTP/1.1Host: api.endpoint.peAuthorization: Bearer ep_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

No se aceptan claves en la query string ni en otras cabeceras. La petición debe ir por HTTPS.

Formato de la clave

ep_live_ seguido de 40 caracteres alfanuméricos (48 en total). En el panel cada clave se identifica por su prefijo y sus últimos cuatro caracteres, por ejemplo ep_live_3f9a···k2Qp; la clave completa solo se muestra al crearla.

Errores de autenticación

HTTP	`error`	Cuándo
401	`token_invalido`	Falta la cabecera, no usa el esquema `Bearer`, la clave no tiene el formato esperado o no existe.
403	`token_inactivo`	La clave está desactivada o fue revocada desde el panel.
403	`cuenta_suspendida`	La cuenta dueña de la clave está suspendida.

Las respuestas 401 llevan la cabecera WWW-Authenticate: Bearer. Ninguna de estas respuestas descuenta créditos.

respuesta.json

{  "success": false,  "message": "La API key no es válida.",  "error": "token_invalido",  "data": null,  "meta": {    "consultado_en": "2026-10-12T08:41:49Z"  }}

Estados de una API key

Activa: funciona con normalidad.
Inactiva: la desactivaste desde el panel; responde 403 hasta que la vuelvas a activar. Sirve para pausar un sistema sin perder la clave.
Revocada: eliminada para siempre; responde 403 y no se puede recuperar.

Cómo cuidarla

Usa una clave por sistema o por entorno (producción, pruebas). Así puedes revocar una sin afectar a las demás y ver el consumo de cada una en Estadísticas.
Guárdala en variables de entorno o en tu gestor de secretos, nunca en el código ni en el repositorio.
No la uses desde el navegador ni desde una app móvil: cualquiera podría leerla. Haz la consulta desde tu servidor y entrega a tus usuarios solo el resultado.
Para rotarla sin cortes: crea la clave nueva, despliega, y recién entonces revoca la anterior.
Si sospechas que se filtró, revócala de inmediato desde el panel y revisa en el Historial qué consultas se hicieron con ella.

Más en Seguridad de tokens de API: buenas prácticas.