Ir para o conteúdo

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-Key que 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:read e insights: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 com 403 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, remaining e resetIn (segundos até o reinício, no dia 1 às 00:00 UTC). É o mesmo contador que decide o 429. Qualquer um pode ser null: limit e resetIn numa chave sem limite; consumed e remaining se o contador não puder ser lido naquele momento.
  • usageHistory: seu uso contábil dos últimos 12 meses (UTC), incluindo o em curso. months vai do mais recente ao mais antigo; cada mês traz requests, quotaUnits, rejectedRequests (os 429), logoAnalyses e byScope (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: 400 e title: "Request validation failed" para um escopo que falta. Quem ramifica por code nã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ção 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": "..." }
  • 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, requestId e, numa falha de validação, errors[]), descrito no guia de primeiros passos. Use requestId (o mesmo valor que viaja no header de resposta X-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 do Origin); nenhuma credencial é enviada (credentials:false). Um preflight OPTIONS dessas 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 fetch de 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.