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-Keyvalue 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:readandinsights: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 with403 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.
Paid signup (manual)
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,remainingandresetIn(seconds until the reset, on the 1st at 00:00 UTC). It is the same counter that decides the429. Any of them can benull:limitandresetInon a key with no limit;consumedandremainingwhen the counter cannot be read at that moment.usageHistory: your accounted usage over the last 12 months (UTC), the current one included.monthsruns from newest to oldest; each month carriesrequests,quotaUnits,rejectedRequests(the429s),logoAnalysesandbyScope(the same breakdown per operation family).asOfis 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.consumedslightly (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: 400andtitle: "Request validation failed"for a missing scope. Code that branches oncodeneeds 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 new429condition.
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,requestIdand, on a validation failure,errors[]), described in the getting-started guide. UserequestId(the same value carried in theX-Correlation-IDresponse 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-Originheader) — the default no-op. - With origins → only those exact origins receive the
Access-Control-Allow-Originheader (never a wildcard, never arbitraryOriginreflection); no credentials are sent (credentials:false). A preflightOPTIONSfrom 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.