Autenticação e escopos
Todo endpoint protegido do contrato de leitura do Tarno é controlado por uma chave de API. Este guia
cobre como apresentar a chave, os escopos, o ciclo de vida da chave e a semântica exata de 401 / 403 /
429 — tudo alinhado com os handlers ao vivo.
O header X-API-Key
Envie sua chave no header de requisição X-API-Key em toda chamada a uma rota protegida:
curl -sS "$TARNO_BASE_URL/trademarks?limit=1" -H "X-API-Key: $TARNO_API_KEY"
A chave é uma string opaca emitida pelo operador (placeholder <API_KEY> nesta documentação). O
servidor a verifica em toda requisição; a chave bruta nunca é registrada em log.
O servidor MCP usa o mesmo header X-API-Key, enviado por requisição sobre o transporte
Streamable HTTP — veja o guia MCP. (Para o transporte stdio, a chave é lida da
variável de ambiente TARNO_API_KEY.)
Rotas públicas que não precisam de chave
/health, /docs e /metrics são os únicos caminhos que funcionam sem chave. Tudo
o resto exige uma.
Escopos
Uma chave carrega um conjunto de escopos (scopes) que determinam quais partes do contrato ela pode ler:
| Escopo | Concede acesso a |
|---|---|
brands:read |
O corpus de marcas: /trademarks/* (busca, ficha, prazos, anotações de uma marca, comparação, calendário de renovações), /annotations/*, /parties/*, /nice-classes/*, /sections/*, a lista e a ficha de uma norma (GET /legal-norms, GET /legal-norms/{id}), POST /fee-schedule/calculate e GET /business-days. |
insights:read |
O contrato operacional e as agregações: /system/* (freshness, coverage, vigilance-horizon, sync-runs, me), /insights/trademarks (GET e POST …/search) e GET /holidays. |
watch:read |
Leituras de Vigilância de semelhantes: GET /watch/applications (≡ list_watched_applications) e GET /watch/hits (≡ list_similarity_hits). |
watch:write |
Escritas de Vigilância: POST /watch/applications (≡ watch_application) e DELETE /watch/applications/{applicationNumber} (≡ unwatch_application). Até 2026-10-04 essas duas permissões abriam as rotas /watchlists, retiradas nesse dia. |
reports:read |
Todos os relatórios de uma chamada (/reports/*): concede por si só cada reports:<relatório>:read, não é preciso somá-los. |
reports:<relatório>:read |
Um relatório: 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 e, desde 2026-09-29, reports:conflict-landscape:read (GET /reports/conflict-landscape, o panorama de conflito: nem uma chave sem restrição nem reports:clearance:read o recebem) , reports:registration-signals:read (GET /reports/registration-signals, o índice orientativo, mesma regra) e reports:filing-context:read (GET /reports/filing-context, o dossiê de fatos de uma peça: nem uma chave sem restrição nem as permissões das peças de oposição o recebem). ⚠ Dupla permissão: com expand=legalTexts o dossiê exige também legal:read; sem ela, 403 que a nomeia, sem cota. |
legal:read |
A base documental: o texto literal das leis numa data (GET /legal-norms/{id}/articles/{article}), as Diretrizes do INAPI (/guidance/*), a pesquisa, as taxas, os indicadores e, junto com brands:read, a citação explicada (GET /annotations/{id}?expand=citations) (guia). |
logo:analyze |
A análise de um logotipo por um modelo de linguagem (POST /logos/analyze ≡ analyze_logo). Cada chamada custa dinheiro num terceiro (Anthropic) e tem ainda uma cota diária própria (20 por chave, 200 no total). Nem uma chave irrestrita, nem a de teste, nem reports:read a recebem. |
logo:similar |
A semelhança por imagem (POST /logos/similar ≡ find_similar_logos), uma operação futura: hoje responde sempre 503 image_similarity_not_available. Nem uma chave irrestrita, nem a de teste, nem reports:read, nem logo:analyze a recebem. ⚠ Não é concedida a nenhuma chave até que a operação seja anunciada como disponível. |
Um array de escopos vazio é irrestrito — uma chave emitida sem escopos recebe todos os
escopos de leitura, exceto os de relatórios, legal:read e os de logotipos (logo:analyze, logo:similar). ⛔
watch:write, as permissões reports:*, legal:read e logo:* são sempre concedidas explicitamente: uma chave
irrestrita não as recebe, nem a chave de teste (os relatórios e a base documental são vendidos à parte, e a
análise de logotipos custa dinheiro num terceiro; veja relatórios, a
base documental e a análise de um logotipo). Uma chave com um array de escopos não vazio recebe somente os escopos listados; chamar
uma rota cujo escopo exigido está ausente é rejeitado com 403 forbidden.
⚠ Para quem concede chaves: passar uma chave de [] para ["legal:read"] REMOVE todas as outras
leituras — uma lista não vazia é uma lista fechada. Para acrescentar legal:read a uma chave irrestrita, é
preciso escrever a lista completa (por exemplo ["brands:read", "insights:read", "watch:read",
"legal:read"]).
Chave base de uma organização (plano base): a chave que o provisionamento cria leva seis permissões: brands:read, insights:read, watch:read, watch:write, legal:read e reports:read (esta abre todos os /reports/*; os reports:<relatório>:read não são necessários). Nunca leva logo:*. As permissões são definidas pelo plano da organização e copiadas para a chave ao emiti-la ou rotacioná-la; mudar o plano não altera chaves já emitidas (as chaves vivas já foram atualizadas).
Os escopos watch:* exigem adicionalmente que a chave tenha uma org dona (consumerId); veja o
guia de Vigilância para tenancy, os limites e como se leem as semelhantes.
As ferramentas MCP seguem a mesma regra: tanto search_trademarks quanto get_trademark exigem
brands:read (ou uma chave irrestrita, de escopo vazio).
⭐ Dois escopos num pedido: o detalhe de uma anotação (GET /annotations/{id} ≡ get_annotation)
exige brands:read, e com expand=citations (a citação
explicada) exige também legal:read. A mesma regra vale para a ficha de
uma marca com expand=norms (GET /trademarks/{applicationNumber}?expand=norms ≡ get_trademark, que exige
brands:read + legal:read) e para o dossiê de um escrito com expand=legalTexts
(GET /reports/filing-context?expand=legalTexts ≡ get_filing_context, que exige
reports:filing-context:read + legal:read). Sem ela, 403 forbidden que nomeia legal:read, sem consumir
quota, em REST e em MCP.
Ciclo de vida da chave (gerenciado pelo operador)
As chaves são criadas, rotacionadas, revogadas e expiradas pelo operador pelo portal do operador. Como integrador, você não gerencia chaves por conta própria; você solicita mudanças ao seu operador.
- Rotacionar — o operador lhe emite uma nova chave e desativa a antiga. Troque o
valor de
X-API-Keyque seu cliente envia; nenhuma mudança de código além do segredo. - Revogar — uma chave revogada para de funcionar imediatamente: as chamadas seguintes retornam
401 unauthorized, exatamente como para uma chave desconhecida. - Expiração — uma chave pode carregar uma data de expiração. Após passar da expiração, ela é tratada como inválida e
retorna
401 unauthorized. Peça ao seu operador para reemitir antes da expiração para evitar indisponibilidade.
Cada chave também pertence a um consumer e carrega uma cota mensal (veja abaixo).
Chave de teste pública
Para avaliar o produto sem falar conosco, existe uma chave de teste pública:
tarno_9NgfSzUkeaa8cdaEc3Wrrw7wqcX67FTbM78a6dcVLUk
- Somente leitura:
brands:readeinsights:read. - Cota reduzida: 1.000 requisições por mês — claramente menor que a de uma chave paga.
- ⛔ Ela não escreve nada: não cadastra nem remove solicitações em vigilância (
watch:write), e não consegue nem ler o que é vigiado (watch:read). Qualquer tentativa de escrita é rejeitada com403 forbidden.
Com ela você percorre o caminho de um avaliador: buscar marcas, ler um processo e ver seu próprio
estado com GET /system/me (identidade, escopos, cota consumida e limite). Esgotar a cota devolve o
429 quota_exceeded habitual, com o Retry-After até o mês reiniciar.
Cadastro de um cliente pago (manual)
Até que haja volume, o cadastro pago é manual: um operador registra o consumidor e emite sua chave
pelo portal do operador — não há autosserviço. Para passar do teste ao pago, escreva ao seu contato
operador indicando os escopos de que precisa e a cota mensal que deseja contratar; ele emitirá uma
chave com sua org própria e os watch:* que seu caso exigir.
Seu uso: GET /system/me ≡ get_system_me
Com o escopo insights:read, GET /system/me (MCP get_system_me, mesma resposta) devolve o que é
da sua própria chave, nada de outras chaves nem do sistema:
consumerId,name,scopes: sua organização e seus escopos.quota: o mês em curso ao vivo —limit,consumed,remainingeresetIn(segundos até o reinício, no dia 1 às 00:00 UTC). É o mesmo contador que decide o429. Qualquer um pode sernull:limiteresetInnuma chave sem limite;consumederemainingse o contador não puder ser lido naquele momento.usageHistory: seu uso contábil dos últimos 12 meses (UTC), incluindo o em curso.monthsvai do mais recente ao mais antigo; cada mês trazrequests,quotaUnits,rejectedRequests(os429),logoAnalysesebyScope(o mesmo detalhamento por família da operação).asOfé a última vez em que se registrou uso da sua chave.
"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 } ] }
]
}
- Um mês que não aparece é um mês sem uso registrado, não um zero calculado. O registro contábil começa em 2026-10-03: antes dessa data não há histórico.
- O mês em curso pode ficar um pouco atrás de
quota.consumed(cerca de um minuto): o histórico é a contabilidade, consolidada em segundo plano; a cota é o contador ao vivo. - É por chave: se sua organização tem várias chaves, cada uma vê o seu.
503 service_unavailable(reexecutável) se a base de plataforma —onde vivem as chaves e as organizações— não responder.
Semântica de status
Estes são os resultados exatos que as camadas de autenticação e cota produzem:
401 unauthorized
Retornado quando a chave está ausente, malformada, desconhecida ou revogada/expirada.
{ "type": "https://api.tarno.cl/problems/unauthorized", "title": "Unauthorized", "status": 401,
"detail": "Missing or invalid API key", "code": "unauthorized", "requestId": "..." }
403 forbidden
Retornado quando a chave é válida e ativa, mas não tem o escopo que a rota exige. A mensagem nomeia o escopo 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, o mesmo corpo. Uma ferramenta chamada com uma chave sem o escopo devolve um resultado de
tools/call com isError: true cujo texto é o MESMO JSON que o do REST —status: 403, title:
"Forbidden", code: "forbidden" e o mesmo detail que nomeia o escopo—; só requestId vai vazio (o
MCP não expõe um próprio). Uma chave ausente ou revogada dá, igualmente, o corpo do 401. Também não
consome cota.
{ "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\":\"\"}" }] }
Até 2026-09-28 esse texto dizia
status: 400etitle: "Request validation failed"para um escopo que falta. Quem ramifica porcodenão precisa mudar nada.
429 quota_exceeded
Retornado quando a cota mensal está esgotada: a da chave ou a da sua organização. O plano de
uma organização pode ter uma cota mensal para todas as suas chaves juntas; cada chave pode ter
ainda a sua, mais baixa. Vale a que se esgotar primeiro, e é ela que os headers RateLimit-* e
quota em GET /system/me descrevem. Carrega um header Retry-After com os
segundos até a janela de cota reiniciar:
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
Existem dois limites de taxa, ambos aditivos à cota mensal, e ambos retornam 429 com um header
Retry-After (segundos a aguardar):
- Rajada por chave (
code: rate_limited) — um segundo nível baseado no hash da chave que limita um único inquilino: por padrão 300 requisições a cada 60 s. Aplica-se de forma idêntica em REST e no MCP (ambos os transportes compartilham o mesmo contador), é independente do IP do cliente (então um pool de IP rotativo não o contorna) e não altera o esquema do contrato de leitura — é uma nova condição429puramente 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": "..." }
- Defesa anti-inundação por IP (
code: rate_limited) — um limite baseado no IP do cliente (padrão 100 requisições/minuto no REST e 30 requisições/segundo no MCP) que contém uma avalanche pré-autenticação (chaves rotativas). É independente do nível por chave.
Atrás do gateway. api.tarno.cl e mcp.tarno.cl podem ser servidos através de um gateway que
encaminha cada requisição ao núcleo. Nesse caso, o «IP do cliente» deste limite é o que o gateway afirma
no cabeçalho x-gateway-client-ip, somente se a requisição também traz x-gateway-secret com o
segredo compartilhado entre gateway e núcleo (comparado em tempo constante) e o IP é válido (IPv4 ou
IPv6). Em qualquer outro caso —sem segredo configurado, segredo que não confere, IP ausente ou inválido—
os dois cabeçalhos são ignorados e o limite usa o IP de sempre. São cabeçalhos de infraestrutura,
não do contrato do consumidor: não os envie (o gateway remove qualquer x-gateway-* de entrada e, sem o
segredo, não têm efeito). x-gateway-secret nunca é registrado nem devolvido. A cota mensal, a rajada
por chave e a autenticação não mudam.
Ação do consumidor: respeite o Retry-After e tente novamente após esse número de segundos. A cota
mensal (quota_exceeded) e a rajada por chave (rate_limited) se aplicam de forma idêntica em REST
e no MCP, já que ambos os transportes se autenticam contra as mesmas chaves e compartilham os mesmos
contadores; o limite por IP é próprio de cada transporte.
Se a base de chaves não responder. Uma chave que o serviço validou nos últimos 15 minutos continua
funcionando; uma que ele não viu recebe 503 service_unavailable (reexecutável), nunca 401.
GET /system/me ≡ get_system_me responde 503 enquanto durar.
Todo erro traz um corpo RFC 9457 (
application/problem+json:type,title,status,detail,code,requestIde, numa falha de validação,errors[]), descrito no guia de primeiros passos. UserequestId(o mesmo valor que viaja no header de respostaX-Correlation-ID) ao relatar um problema ao seu operador.
CORS e acesso pelo navegador
O Tarno é server-side-only por padrão: a X-API-Key é uma credencial de servidor e nunca deve ser
embutida em um cliente de navegador. Por isso, por padrão a API não emite nenhum header
Access-Control-Allow-Origin — um fetch de navegador de terceiros não consegue ler as respostas. Este é
o comportamento padrão e não muda nada em relação a versões anteriores.
O acesso cross-origin pelo navegador é opt-in por deploy através da variável de ambiente
TARNO_CORS_ALLOWLIST (lista de origens exatas separadas por vírgulas):
TARNO_CORS_ALLOWLIST=https://app.tarno.cl,https://docs.tarno.cl
- Vazia / não definida → sem CORS (sem header
Access-Control-Allow-Origin) — o padrão no-op. - Com origens → apenas essas origens exatas recebem o header
Access-Control-Allow-Origin(nunca um curinga nem reflexo arbitrário doOrigin); nenhuma credencial é enviada (credentials:false). Um preflightOPTIONSdessas origens é respondido com os headers de permissão.
O servidor MCP não usa CORS. O MCP é um transporte servidor-a-servidor (agentes de IA o chamam pela rede, não um
fetchde navegador), então CORS — uma salvaguarda do navegador — não se aplica ali.
Veja também
- Primeiros passos — URL base, primeira chamada, paginação, envelope de erro.
- Conecte seu agente de IA (MCP) — mesma chave, mesmos escopos, via MCP.
- A referência OpenAPI ao vivo em
/docs— segurança e schema por endpoint.