Autenticación y scopes

Cada endpoint protegido del contrato de lectura de IRIS está controlado por una clave de API. Esta guía cubre cómo presentar la clave, los dos scopes, el ciclo de vida de la clave y la semántica exacta de 401 / 403 / 429 — todo en concordancia con los handlers en vivo.

El encabezado `X-API-Key`

Envía tu clave en el encabezado de solicitud X-API-Key en cada llamada a una ruta protegida:

curl -sS "$IRIS_BASE_URL/v1/brands?limit=1" -H "X-API-Key: $IRIS_API_KEY"

La clave es una cadena opaca emitida por el operador (marcador de posición iris_xxx en esta documentación). El servidor la verifica en cada solicitud; la clave en crudo nunca se registra en logs.

El servidor MCP usa el mismo encabezado X-API-Key, enviado por solicitud sobre el transporte Streamable HTTP — consulta la guía de MCP. (Para el transporte stdio, la clave se lee de la variable de entorno IRIS_API_KEY en su lugar.)

Rutas públicas que no necesitan clave

/health, /docs y /metrics son las únicas rutas que funcionan sin clave. Todo lo que está bajo /v1 requiere una.

Scopes

Una clave lleva un conjunto de scopes que determinan qué partes del contrato puede leer:

Scope	Otorga acceso a
`brands:read`	El contrato de marcas: `GET /v1/brands`, `GET /v1/brands/:nroSolicitud`.
`insights:read`	El contrato operacional: `GET /v1/freshness`, `GET /v1/sync-runs`.

Un arreglo de scopes vacío no tiene restricción — una clave emitida sin scopes recibe todos los scopes de lectura. Una clave con un arreglo de scopes no vacío recibe solo los scopes listados; llamar a una ruta cuyo scope requerido está ausente se rechaza con 403 forbidden.

Las herramientas de MCP siguen la misma regla: tanto search_brands como get_brand_detail requieren brands:read (o una clave sin restricción, con scopes vacíos).

Ciclo de vida de la clave (gestionado por el operador)

Las claves se crean, rotan, revocan y expiran por el operador a través de la CLI de administración. Como integrador, tú no gestionas las claves por tu cuenta; solicitas los cambios a tu operador.

Rotar — el operador te emite una clave nueva y da de baja la antigua. Cambia el valor X-API-Key que tu cliente envía; sin cambios de código más allá del secreto.
Revocar — una clave revocada deja de funcionar de inmediato: las llamadas posteriores devuelven 401 unauthorized, exactamente como con una clave desconocida.
Expiración — una clave puede llevar una fecha de expiración. Una vez pasada la expiración se trata como inválida y devuelve 401 unauthorized. Pídele a tu operador que la reemita antes de la expiración para evitar caídas.

Cada clave también pertenece a un consumidor y lleva una cuota mensual (ver más abajo).

Semántica de estados

Estos son los resultados exactos que producen las capas de autenticación y cuota:

`401 unauthorized`

Se devuelve cuando la clave está ausente, malformada, es desconocida o está revocada/expirada.

{ "error": { "code": "unauthorized", "message": "Missing or invalid API key", "requestId": "..." } }

`403 forbidden`

Se devuelve cuando la clave es válida y está activa, pero le falta el scope que la ruta requiere. El mensaje nombra el scope faltante:

{ "error": { "code": "forbidden", "message": "API key lacks required scope: insights:read", "requestId": "..." } }

`429 quota_exceeded`

Se devuelve cuando la cuota mensual de la clave está agotada. Lleva un encabezado Retry-After con los segundos hasta que la ventana de cuota se reinicia:

HTTP/1.1 429 Too Many Requests
Retry-After: 1209600

{ "error": { "code": "quota_exceeded", "message": "Monthly quota exceeded", "requestId": "..." } }

Un límite de ráfaga de corto plazo aparte (por defecto 100 solicitudes/minuto por clave) también devuelve 429. Tanto el límite de ráfaga como la cuota mensual aplican de forma idéntica en REST y en el MCP, ya que ambos transportes se autentican contra las mismas claves y comparten el mismo contador de cuota.

El sobre de error uniforme { error: { code, message, requestId } } se describe en la guía de primeros pasos. Usa requestId (también reflejado en el encabezado de respuesta x-request-id) al reportar un problema a tu operador.

Ver también

Primeros pasos — URL base, primera llamada, paginación, sobre de error.
Conecta tu agente de IA (MCP) — misma clave, mismos scopes, sobre MCP.
La referencia OpenAPI en vivo en /docs — seguridad y esquema por endpoint.