Saltar a contenido

Autenticación y scopes

Cada endpoint protegido del contrato de lectura de Tarno está controlado por una clave de API. Esta guía cubre cómo presentar la clave, los 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 "$TARNO_BASE_URL/trademarks?limit=1" -H "X-API-Key: $TARNO_API_KEY"

La clave es una cadena opaca emitida por el operador (marcador de posición <API_KEY> 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 TARNO_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 demás 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 corpus de marcas: /trademarks/* (búsqueda, ficha, plazos, anotaciones de una marca, comparación, calendario de renovaciones), /annotations/*, /parties/*, /nice-classes/*, /sections/*, la lista y la ficha de una norma (GET /legal-norms, GET /legal-norms/{id}), POST /fee-schedule/calculate y GET /business-days.
insights:read El contrato operacional y las agregaciones: /system/* (freshness, coverage, vigilance-horizon, sync-runs, me), /insights/trademarks (GET y POST …/search) y GET /holidays.
watch:read Lecturas de Vigilancia de parecidos: GET /watch/applications (≡ list_watched_applications) y GET /watch/hits (≡ list_similarity_hits).
watch:write Escrituras de Vigilancia: POST /watch/applications (≡ watch_application) y DELETE /watch/applications/{applicationNumber} (≡ unwatch_application). Hasta el 2026-10-04 estos dos permisos abrían las rutas /watchlists, retiradas ese día.
reports:read Todos los informes de una llamada (/reports/*): concede por sí solo cada reports:<informe>:read, no hace falta sumarlos.
reports:<informe>:read Un informe: reports:daily-bulletin:read (GET /reports/daily-bulletin), reports:clearance:read (GET /reports/clearance), reports:portfolio:read, reports:opposition-brief:read, reports:opposition-response-brief:read y, desde el 2026-09-29, reports:conflict-landscape:read (GET /reports/conflict-landscape, el panorama de conflicto: ni una clave sin restricción ni reports:clearance:read lo reciben) , reports:registration-signals:read (GET /reports/registration-signals, el índice orientativo, con la misma regla) y reports:filing-context:read (GET /reports/filing-context, el expediente de hechos de un escrito: ni una clave sin restricción ni los permisos de los escritos de oposición lo reciben). ⚠ Doble permiso: con expand=legalTexts el expediente exige además legal:read; sin él, 403 que lo nombra, sin cuota.
legal:read La base documental: el texto literal de las leyes a una fecha (GET /legal-norms/{id}/articles/{article}), las Directrices de INAPI (/guidance/*), la búsqueda, las tasas, los indicadores y, junto con brands:read, la cita explicada (GET /annotations/{id}?expand=citations) (guía).
logo:analyze El análisis de un logo con un modelo de lenguaje (POST /logos/analyze ≡ analyze_logo). Cada llamada cuesta dinero en un tercero (Anthropic) y lleva además una cuota diaria propia (20 por clave, 200 en total). Ni una clave sin restricción, ni la de prueba, ni reports:read lo reciben.
logo:similar El parecido por imagen (POST /logos/similar ≡ find_similar_logos), una operación futura: hoy responde siempre 503 image_similarity_not_available. Ni una clave sin restricción, ni la de prueba, ni reports:read, ni logo:analyze lo reciben. ⚠ No se concede a ninguna clave hasta que la operación se anuncie disponible.

Un arreglo de scopes vacío no tiene restricción — una clave emitida sin scopes recibe todos los scopes de lectura, salvo los de informes, legal:read y los de logos (logo:analyze, logo:similar). ⛔ watch:write, los permisos reports:*, legal:read y logo:* se conceden siempre explícitamente: una clave sin restricción no los recibe, y la clave de prueba tampoco (los informes y la base documental se venden aparte, y el análisis de logos cuesta dinero en un tercero; ver informes, base documental y análisis de un logo). 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.

⚠ Para quien concede claves: pasar una clave de [] a ["legal:read"] le QUITA todas las demás lecturas — una lista no vacía es una lista cerrada. Para añadir legal:read a una clave sin restricción hay que escribir la lista completa (por ejemplo ["brands:read", "insights:read", "watch:read", "legal:read"]).

Clave base de una organización (plan base): la clave que crea el aprovisionamiento lleva seis permisos: brands:read, insights:read, watch:read, watch:write, legal:read y reports:read (este último abre todos los /reports/*; no hacen falta los reports:<informe>:read). Nunca lleva logo:*. Los permisos los fija el plan de la organización y se copian a la clave al emitirla o rotarla; cambiar el plan no toca claves ya emitidas (las claves vivas ya se actualizaron).

Los scopes watch:* requieren además que la clave tenga una org dueña (consumerId); consulta la guía de Vigilancia para la tenencia, los topes y cómo se leen las parecidas.

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

⭐ Dos permisos en una petición: el detalle de una anotación (GET /annotations/{id} ≡ get_annotation) exige brands:read, y con expand=citations (la cita explicada) exige además legal:read. La misma regla vale para la ficha de una marca con expand=norms (GET /trademarks/{applicationNumber}?expand=norms ≡ get_trademark, que exige brands:read + legal:read) y para el expediente de un escrito con expand=legalTexts (GET /reports/filing-context?expand=legalTexts ≡ get_filing_context, que exige reports:filing-context:read + legal:read). Sin él, 403 forbidden que nombra legal:read, sin consumir cuota, en REST y en MCP.

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

Las claves se crean, rotan, revocan y expiran por el operador desde el portal de operador. 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).

Clave de prueba pública

Para evaluar el producto sin escribirnos existe una clave de prueba pública:

tarno_9NgfSzUkeaa8cdaEc3Wrrw7wqcX67FTbM78a6dcVLUk
  • Sólo lectura: brands:read y insights:read.
  • Cuota reducida: 1.000 peticiones al mes — claramente menor que la de una clave de pago.
  • ⛔ No escribe nada: no da de alta ni de baja solicitudes en vigilancia (watch:write), y ni siquiera puede leer lo vigilado (watch:read). Cualquier intento de escritura se rechaza con 403 forbidden.

Con ella recorres el camino de un evaluador: buscar marcas, leer un expediente y ver tu propio estado con GET /system/me (identidad, alcances, cuota consumida y límite). Agotar su cuota devuelve el 429 quota_exceeded habitual, con su Retry-After hasta el reinicio del mes.

Alta de un cliente de pago (manual)

Hasta que haya volumen, el alta de pago es manual: un operador registra el consumidor y emite su clave desde el portal de operador — no hay autoservicio. Para pasar de la prueba al pago, escribe a tu contacto de operador indicando los alcances que necesitas y la cuota mensual que quieres contratar; te emitirá una clave con tu org propia y los watch:* que tu caso requiera.

Tu uso: GET /system/me ≡ get_system_me

Con el alcance insights:read, GET /system/me (MCP get_system_me, misma respuesta) devuelve lo de tu propia clave, nada de otras claves ni del sistema:

  • consumerId, name, scopes: tu organización y tus alcances.
  • quota: el mes en curso en vivo — limit, consumed, remaining y resetIn (segundos hasta el reinicio, el día 1 a las 00:00 UTC). Es el mismo contador que decide el 429. Cualquiera puede ser null: limit y resetIn en una clave sin límite; consumed y remaining si el contador no se puede leer en ese momento.
  • usageHistory: tu uso contable de los últimos 12 meses (UTC), el en curso incluido. months va del más reciente al más antiguo; cada mes trae requests, quotaUnits, rejectedRequests (los 429), logoAnalyses y byScope (el mismo desglose por la familia de la operación). asOf es la última vez que se registró uso de tu clave.
"usageHistory": {
  "windowMonths": 12,
  "asOf": "2026-10-04T17:41:10.000Z",
  "months": [
    { "month": "2026-10", "requests": 14, "quotaUnits": 14, "rejectedRequests": 0, "logoAnalyses": 0,
      "byScope": [ { "scope": "brands:read", "requests": 12, "quotaUnits": 12, "rejectedRequests": 0 },
                   { "scope": "insights:read", "requests": 2, "quotaUnits": 2, "rejectedRequests": 0 } ] }
  ]
}
  • Un mes que no aparece es un mes sin uso registrado, no un cero calculado. El registro contable empieza el 2026-10-03: antes de esa fecha no hay histórico.
  • El mes en curso puede ir un poco por detrás de quota.consumed (alrededor de un minuto): el histórico es la contabilidad, que se consolida en segundo plano; la cuota es el contador en vivo.
  • Es por clave: si tu organización tiene varias claves, cada una ve el suyo.
  • 503 service_unavailable (reintentable) si la base de plataforma —donde viven las claves y las organizaciones— no contesta.

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.

{ "type": "https://api.tarno.cl/problems/unauthorized", "title": "Unauthorized", "status": 401,
  "detail": "Missing or invalid API key", "code": "unauthorized", "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:

{ "type": "https://api.tarno.cl/problems/forbidden", "title": "Forbidden", "status": 403,
  "detail": "API key lacks required scope: insights:read", "code": "forbidden", "requestId": "..." }

Por MCP, el mismo cuerpo. Una herramienta llamada con una clave sin el scope devuelve un resultado de tools/call con isError: true cuyo texto es el MISMO JSON que el de REST —status: 403, title: "Forbidden", code: "forbidden" y el mismo detail que nombra el scope—; sólo requestId va vacío (el MCP no expone uno propio). Una clave ausente o revocada da, igual, el cuerpo del 401. Tampoco consume cuota.

{ "isError": true,
  "content": [{ "type": "text",
    "text": "{\"type\":\"https://api.tarno.cl/problems/forbidden\",\"title\":\"Forbidden\",\"status\":403,\"detail\":\"API key lacks required scope: insights:read\",\"code\":\"forbidden\",\"requestId\":\"\"}" }] }

Hasta el 2026-09-28 ese texto decía status: 400 y title: "Request validation failed" para un permiso que falta. Quien ramifique por code no tiene que cambiar nada.

429 quota_exceeded

Se devuelve cuando la cuota mensual está agotada: la de la clave o la de su organización. El plan de una organización puede llevar una cuota mensual para todas sus claves juntas; cada clave puede tener además la suya, más baja. Cuenta la que antes se agote, y es la que describen las cabeceras RateLimit-* y quota en GET /system/me. 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

{ "type": "https://api.tarno.cl/problems/quota_exceeded", "title": "Rate limit exceeded", "status": 429,
  "detail": "Monthly quota exceeded", "code": "quota_exceeded", "requestId": "..." }

429 rate_limited

Existen dos límites de tasa, ambos aditivos a la cuota mensual y ambos devuelven 429 con un encabezado Retry-After (segundos a esperar):

  • Ráfaga por clave (code: rate_limited) — un segundo nivel por hash de la clave que acota a un solo inquilino: por defecto 300 solicitudes cada 60 s. Aplica de forma idéntica en REST y en el MCP (ambos transportes comparten el mismo contador), es independiente de la IP del cliente (por lo que un pool de IP rotatorio no lo esquiva) y no cambia el esquema del contrato de lectura — es una nueva condición 429 puramente aditiva.
HTTP/1.1 429 Too Many Requests
Retry-After: 42

{ "type": "https://api.tarno.cl/problems/rate_limited", "title": "Rate limit exceeded", "status": 429,
  "detail": "Too many requests (per-key burst limit)", "code": "rate_limited", "requestId": "..." }
  • Defensa anti-inundación por IP (code: rate_limited) — un límite por IP de cliente (por defecto 100 solicitudes/minuto en REST y 30 solicitudes/segundo en el MCP) que frena una avalancha previa a la autenticación (claves rotatorias). Es independiente del nivel por clave.

Detrás del gateway. api.tarno.cl y mcp.tarno.cl pueden servirse a través de un gateway que reenvía cada petición al núcleo. En ese caso la «IP de cliente» de este límite es la que el gateway afirma en la cabecera x-gateway-client-ip, sólo si la petición trae también x-gateway-secret con el secreto compartido entre gateway y núcleo (comparado en tiempo constante) y la IP es válida (IPv4 o IPv6). En cualquier otro caso —sin secreto configurado, secreto que no coincide, IP ausente o inválida— las dos cabeceras se ignoran y el límite usa la IP de siempre. Son cabeceras de infraestructura, no del contrato del consumidor: no las envíes (el gateway borra cualquier x-gateway-* entrante, y sin el secreto no tienen efecto). x-gateway-secret nunca se registra ni se devuelve. Ni la cuota mensual, ni la ráfaga por clave, ni la autenticación cambian.

Acción del consumidor: respeta el Retry-After y reintenta después de ese número de segundos. La cuota mensual (quota_exceeded) y la ráfaga por clave (rate_limited) aplican de forma idéntica en REST y en el MCP, ya que ambos transportes se autentican contra las mismas claves y comparten los mismos contadores; el límite por IP es propio de cada transporte.

Si la base de claves no contesta. Una clave que el servicio validó en los últimos 15 minutos sigue funcionando; una que no ha visto recibe 503 service_unavailable (reintentable), nunca 401. GET /system/me ≡ get_system_me responde 503 mientras dure.

Todo error lleva un cuerpo RFC 9457 (application/problem+json: type, title, status, detail, code, requestId y, en un fallo de validación, errors[]), descrito en la guía de primeros pasos. Usa requestId (el mismo valor que viaja en el encabezado de respuesta X-Correlation-ID) al reportar un problema a tu operador.

CORS y acceso desde el navegador

Tarno es server-side-only por defecto: la clave X-API-Key es una credencial de servidor y nunca debe incrustarse en un cliente de navegador. Por eso, de forma predeterminada la API no emite ningún encabezado Access-Control-Allow-Origin — un fetch desde el navegador de un tercero no puede leer las respuestas. Este es el comportamiento por defecto y no cambia nada respecto a versiones previas.

El acceso cross-origin desde navegador es opt-in por despliegue mediante la variable de entorno TARNO_CORS_ALLOWLIST (lista de orígenes exactos separados por comas):

TARNO_CORS_ALLOWLIST=https://app.tarno.cl,https://docs.tarno.cl
  • Vacía / sin definir → sin CORS (sin encabezado Access-Control-Allow-Origin) — el default no-op.
  • Con orígenes → sólo esos orígenes exactos reciben el encabezado Access-Control-Allow-Origin (nunca un comodín ni reflejo arbitrario del Origin); no se envían credenciales (credentials:false). Las peticiones preflight OPTIONS de esos orígenes se responden con los encabezados de permiso.

El servidor MCP no usa CORS. El MCP es un transporte servidor-a-servidor (lo consumen agentes de IA por la red, no un fetch de navegador), así que CORS —una salvaguarda del navegador— no aplica ahí.

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.