Chaves de API

Uma chave de API autoriza um sistema externo, por exemplo o teu ERP, a usar a REST API v1 do exoCortex: abrir tickets, ler o seu estado e adicionar comentários. Cada chave pertence a um tenant e só vê os tickets desse tenant.

Criar uma chave

1. No exoCortex Core, abre Integrations → API keys. Precisas de uma função administrativa, por exemplo it_admin ou integration_admin.
2. Dá à chave um nome que diga quem a usa, por exemplo «Conector ERP».
3. Escolhe os scopes, ou seja, o que a chave pode fazer (ver abaixo).
4. Copia a chave completa e guarda-a no gestor de segredos do sistema que a vai usar. O exoCortex só a mostra uma vez e guarda apenas uma impressão digital: se a perderes, crias uma chave nova.

A chave tem o formato nhk.<keyid>.<secret>. O keyid identifica a chave na lista; o secret fica só contigo.

Scopes

Scope	O que permite
tickets:create	Abrir tickets
tickets:read	Ler o estado de um ticket
tickets:comment	Adicionar comentários a um ticket
tickets:*	Todas as operações sobre tickets
*	Tudo o que a API v1 permite

Atribui a cada chave só os scopes de que precisa. Uma chave sem scopes tem acesso total à API v1: é permitido, mas desaconselhado.

Usar a chave

Envia a chave no cabeçalho Authorization de cada pedido:

POST /api/v1/tickets HTTP/1.1
Host: exocortex-api.ai-exo-cortex.com
Authorization: Bearer nhk.9f2c4e1a7b3d.…
Content-Type: application/json
Idempotency-Key: 6b1f0c4e-2a7d-4b39-9e51-8c3d2f7a1b60

{ "subject": "Payment gateway returns HTTP 502", "priority": "High" }

Em alternativa, podes usar o cabeçalho X-NH-API-Key. O tenant não se indica: o exoCortex obtém-no a partir da chave.

Usa sempre Idempotency-Key quando abres um ticket: se repetires o pedido com a mesma chave de idempotência, recebes o ticket já criado em vez de um duplicado.

Limites de frequência

Cada chave tem um limite de pedidos: o valor predefinido é de 600 pedidos a cada 60 segundos. Cada resposta indica em que ponto estás:

Cabeçalho	Significado
RateLimit-Limit	Pedidos permitidos na janela
RateLimit-Remaining	Pedidos ainda disponíveis
RateLimit-Reset	Segundos até à nova janela
Retry-After	Só com a resposta 429: segundos a aguardar antes de tentar de novo

Erros

Os erros da API v1 devolvem um JSON com ok: false, uma mensagem legível em error e um código estável em code. Baseia a lógica do teu cliente no code, não na mensagem.

code	Estado HTTP	O que fazer
missing_api_key	401	Acrescenta o cabeçalho Authorization
invalid_api_key	401	Verifica a chave: pode estar errada ou ter sido revogada
insufficient_scope	403	Acrescenta à chave o scope indicado em required_scope
api_key_disabled	403	A chave está desativada: usa uma chave ativa
validation_error	400	Corrige o campo indicado em field
not_found	404	O ticket não existe ou não pertence ao tenant da chave
rate_limited	429	Aguarda os segundos indicados em Retry-After
ingest_failed	500	Tenta de novo com a mesma Idempotency-Key

O exoCortex pode acrescentar novos códigos: se receberes um que não conheces, decide com base no estado HTTP.

Revogar uma chave

Em Integrations → API keys revogas uma chave quando um sistema já não a usa ou se achares que foi exposta. A revogação é imediata. A lista mostra também a última utilização de cada chave: ajuda-te a encontrar as chaves inativas.

Chaves nh_… descontinuadas

As chaves no formato antigo nh_… funcionam até 30 de junho de 2027. As respostas a estas chaves contêm os cabeçalhos Deprecation e Sunset. Para migrar, cria uma chave nhk. com os scopes necessários, atualiza o sistema que a usa e depois revoga a chave antiga.