Skip to content

Authentication and scopes

Every protected endpoint of the Tarno read contract is gated by an API key. This guide covers how to present the key, the scopes, the key lifecycle, and the exact 401 / 403 / 429 semantics — all matching the live handlers.

The X-API-Key header

Send your key in the X-API-Key request header on every call to a protected route:

curl -sS "$TARNO_BASE_URL/trademarks?limit=1" -H "X-API-Key: $TARNO_API_KEY"

The key is an opaque string issued by the operator (placeholder <API_KEY> in these docs). The server verifies it on every request; the raw key is never logged.

The MCP server uses the same X-API-Key header, sent per request over the Streamable HTTP transport — see the MCP guide. (For the stdio transport, the key is read from the TARNO_API_KEY environment variable instead.)

Public routes that need no key

/health, /docs, and /metrics are the only paths that work without a key. Everything else requires one.

Scopes

A key carries a set of scopes that determine which parts of the contract it may read:

Scope Grants access to
brands:read The trademark corpus: /trademarks/* (search, record, deadlines, a trademark's annotations, comparison, renewal calendar), /annotations/*, /parties/*, /nice-classes/*, /sections/*, the list and record of a legal norm (GET /legal-norms, GET /legal-norms/{id}), POST /fee-schedule/calculate and GET /business-days.
insights:read The operational contract and aggregates: /system/* (freshness, coverage, vigilance-horizon, sync-runs, me), /insights/trademarks (GET and POST …/search) and GET /holidays.
watch:read Similarity watch reads: GET /watch/applications (≡ list_watched_applications) and GET /watch/hits (≡ list_similarity_hits).
watch:write Watch writes: POST /watch/applications (≡ watch_application) and DELETE /watch/applications/{applicationNumber} (≡ unwatch_application). Until 2026-10-04 these two permissions opened the /watchlists routes, retired that day.
reports:read All one-call reports (/reports/*): on its own it grants every reports:<report>:read, you do not need to add them.
reports:<report>:read One report: 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 and, since 2026-09-29, reports:conflict-landscape:read (GET /reports/conflict-landscape, the conflict landscape: neither a key without restriction nor reports:clearance:read gets it) , reports:registration-signals:read (GET /reports/registration-signals, the orientative index, same rule) and reports:filing-context:read (GET /reports/filing-context, the facts of a filing: neither a key without restriction nor the opposition briefs' permissions get it). ⚠ Double permission: with expand=legalTexts the filing facts require legal:read as well; without it, a 403 naming it, no quota.
legal:read The documentary base: the literal text of the statutes on a date (GET /legal-norms/{id}/articles/{article}), INAPI's guidelines (/guidance/*), the search, the fees, the indicators and, together with brands:read, the explained citation (GET /annotations/{id}?expand=citations) (guide).
logo:analyze The logo analysis by a language model (POST /logos/analyze ≡ analyze_logo). Every call costs money at a third party (Anthropic) and carries its own daily quota as well (20 per key, 200 in total). Neither an unrestricted key, nor the trial key, nor reports:read gets it.
logo:similar The resemblance by image (POST /logos/similar ≡ find_similar_logos), a future operation: today it always answers 503 image_similarity_not_available. Neither an unrestricted key, nor the trial key, nor reports:read, nor logo:analyze gets it. ⚠ It is granted to no key until the operation is announced as available.

An empty scopes array is unrestricted — a key issued with no scopes is granted all read scopes, except the report ones, legal:read and the logo ones (logo:analyze, logo:similar). ⛔ watch:write, the reports:* permissions, legal:read and logo:* are always granted explicitly: an unrestricted key does not get them, nor does the trial key (reports and the documentary base are sold separately, and the logo analysis costs money at a third party; see reports, the documentary base and logo analysis). A key with a non-empty scopes array is granted only the scopes listed; calling a route whose required scope is absent is rejected with 403 forbidden.

⚠ For whoever grants keys: moving a key from [] to ["legal:read"] REMOVES every other read — a non-empty list is a closed list. To add legal:read to an unrestricted key, write the full list (for example ["brands:read", "insights:read", "watch:read", "legal:read"]).

Base key of an organisation (plan base): the key provisioning creates carries six scopes: brands:read, insights:read, watch:read, watch:write, legal:read and reports:read (the last opens every /reports/* route; the reports:<report>:read ones are not needed). It never carries logo:*. The scopes are set by the organisation's plan and are copied to the key when it is issued or rotated; changing the plan does not touch keys already issued (the live keys have already been updated).

The watch:* scopes additionally require the key to have an owning org (consumerId); see the watch guide for tenancy, the caps, and how matches are read.

The MCP tools follow the same rule: both search_trademarks and get_trademark require brands:read (or an unrestricted, empty-scope key).

⭐ Two scopes in one request: the detail of an annotation (GET /annotations/{id} ≡ get_annotation) requires brands:read, and with expand=citations (the explained citation) it also requires legal:read. The same rule applies to a trademark's record with expand=norms (GET /trademarks/{applicationNumber}?expand=norms ≡ get_trademark, which requires brands:read + legal:read) and to a filing's fact file with expand=legalTexts (GET /reports/filing-context?expand=legalTexts ≡ get_filing_context, which requires reports:filing-context:read + legal:read). Without it, 403 forbidden naming legal:read, consuming no quota, on REST and on MCP.

Key lifecycle (operator-managed)

Keys are created, rotated, revoked, and expired by the operator from the operator portal. As an integrator you do not manage keys yourself; you request changes from your operator.

  • Rotate — the operator issues you a new key and decommissions the old one. Switch the X-API-Key value your client sends; no code change beyond the secret.
  • Revoke — a revoked key stops working immediately: subsequent calls return 401 unauthorized, exactly as for an unknown key.
  • Expiry — a key may carry an expiry date. Once past expiry it is treated as invalid and returns 401 unauthorized. Ask your operator to reissue before expiry to avoid downtime.

Each key also belongs to a consumer and carries a monthly quota (see below).

Public trial key

To evaluate the product without talking to us, there is a public trial key:

tarno_9NgfSzUkeaa8cdaEc3Wrrw7wqcX67FTbM78a6dcVLUk
  • Read-only: brands:read and insights:read.
  • Reduced quota: 1,000 requests per month — clearly less than a paid key.
  • ⛔ It can write nothing: it can neither subscribe nor unsubscribe applications for watching (watch:write), and it cannot even read what is watched (watch:read). Any write attempt is rejected with 403 forbidden.

With it you can walk the evaluator path: search trademarks, read a case file, and see your own status via GET /system/me (identity, scopes, quota consumed, and limit). Exhausting its quota returns the usual 429 quota_exceeded with its Retry-After until the month resets.

Until there is volume, paid signup is manual: an operator registers the consumer and issues their key from the operator portal — there is no self-service. To move from trial to paid, write to your operator contact stating the scopes you need and the monthly quota you want; they will issue a key with your own org and the watch:* scopes your use case requires.

Your usage: GET /system/me ≡ get_system_me

With the insights:read scope, GET /system/me (MCP get_system_me, same response) returns what belongs to your own key, nothing about other keys or the system:

  • consumerId, name, scopes: your organisation and your scopes.
  • quota: the current month live — limit, consumed, remaining and resetIn (seconds until the reset, on the 1st at 00:00 UTC). It is the same counter that decides the 429. Any of them can be null: limit and resetIn on a key with no limit; consumed and remaining when the counter cannot be read at that moment.
  • usageHistory: your accounted usage over the last 12 months (UTC), the current one included. months runs from newest to oldest; each month carries requests, quotaUnits, rejectedRequests (the 429s), logoAnalyses and byScope (the same breakdown per operation family). asOf is the last time usage of your key was recorded.
"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 } ] }
  ]
}
  • A month that does not appear is a month with no recorded usage, not a computed zero. Usage accounting starts on 2026-10-03: there is no history before that date.
  • The current month may lag quota.consumed slightly (about a minute): the history is the accounting, consolidated in the background; the quota is the live counter.
  • It is per key: if your organisation has several keys, each one sees its own.
  • 503 service_unavailable (retryable) when the platform database —where keys and organisations live— does not answer.

Status semantics

These are the exact outcomes the auth and quota layers produce:

401 unauthorized

Returned when the key is missing, malformed, unknown, or revoked/expired.

{ "type": "https://api.tarno.cl/problems/unauthorized", "title": "Unauthorized", "status": 401,
  "detail": "Missing or invalid API key", "code": "unauthorized", "requestId": "..." }

403 forbidden

Returned when the key is valid and live, but lacks the scope the route requires. The message names the missing scope:

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

Over MCP, the same body. A tool called with a key that lacks the scope returns a tools/call result with isError: true whose text is the SAME JSON as REST's —status: 403, title: "Forbidden", code: "forbidden" and the same detail naming the scope—; only requestId is empty (MCP exposes none of its own). A missing or revoked key likewise gives the 401 body. It consumes no quota either.

{ "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\":\"\"}" }] }

Until 2026-09-28 that text said status: 400 and title: "Request validation failed" for a missing scope. Code that branches on code needs no change.

429 quota_exceeded

Returned when the monthly quota is exhausted: the key's own, or its organisation's. An organisation's plan may carry a monthly quota for all its keys together; each key may also have its own, lower one. Whichever runs out first applies, and it is the one the RateLimit-* headers and quota in GET /system/me describe. Carries a Retry-After header with the seconds until the quota window resets:

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

There are two rate limits, both additive to the monthly quota, and both return 429 with a Retry-After header (seconds to wait):

  • Per-key burst (code: rate_limited) — a second tier keyed on the key hash that caps a single tenant: by default 300 requests every 60 s. It applies identically on REST and on the MCP (both transports share the same counter), is independent of the client IP (so a rotating IP pool cannot dodge it), and does not change the read contract schema — it is a purely additive new 429 condition.
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": "..." }
  • Per-IP flood defense (code: rate_limited) — a limit keyed on the client IP (default 100 requests/minute on REST and 30 requests/second on the MCP) that blunts a pre-auth flood (rotating keys). It is independent of the per-key tier.

Behind the gateway. api.tarno.cl and mcp.tarno.cl may be served through a gateway that forwards every request to the core. In that case the "client IP" of this limit is the one the gateway asserts in the x-gateway-client-ip header, only when the request also carries x-gateway-secret with the secret shared between gateway and core (compared in constant time) and the IP is valid (IPv4 or IPv6). In every other case —no secret configured, a secret that does not match, a missing or invalid IP— both headers are ignored and the limit uses the usual IP. They are infrastructure headers, not part of the consumer contract: do not send them (the gateway strips any inbound x-gateway-*, and without the secret they have no effect). x-gateway-secret is never logged nor echoed. The monthly quota, the per-key burst and authentication do not change.

Consumer action: honor the Retry-After and retry after that many seconds. The monthly quota (quota_exceeded) and the per-key burst (rate_limited) apply identically on REST and on the MCP, since both transports authenticate against the same keys and share the same counters; the per-IP limit belongs to each transport.

If the key database does not answer. A key the service validated in the last 15 minutes keeps working; one it has not seen gets 503 service_unavailable (retryable), never 401. GET /system/me ≡ get_system_me answers 503 while it lasts.

Every error carries an RFC 9457 body (application/problem+json: type, title, status, detail, code, requestId and, on a validation failure, errors[]), described in the getting-started guide. Use requestId (the same value carried in the X-Correlation-ID response header) when reporting an issue to your operator.

CORS and browser access

Tarno is server-side-only by default: the X-API-Key is a server-side credential and must never be embedded in a browser client. Therefore, by default the API emits no Access-Control-Allow-Origin header — a third-party browser fetch cannot read the responses. This is the default posture and changes nothing relative to prior versions.

Cross-origin browser access is opt-in per deploy via the TARNO_CORS_ALLOWLIST environment variable (a comma-separated list of exact origins):

TARNO_CORS_ALLOWLIST=https://app.tarno.cl,https://docs.tarno.cl
  • Empty / unset → no CORS (no Access-Control-Allow-Origin header) — the default no-op.
  • With origins → only those exact origins receive the Access-Control-Allow-Origin header (never a wildcard, never arbitrary Origin reflection); no credentials are sent (credentials:false). A preflight OPTIONS from those origins is answered with the allow headers.

The MCP server does not use CORS. MCP is a server-to-server transport (AI agents call it over the wire, not a browser fetch), so CORS — a browser safeguard — does not apply there.

See also

  • Getting started — base URL, first call, pagination, error envelope.
  • Connect your AI agent (MCP) — same key, same scopes, over MCP.
  • The live OpenAPI reference at /docs — per-endpoint security and schema.