Openi DeveloperDeveloper
Guia de integração

Autenticação

Chave de API do tenant, escopos e como conferir a chave em uso.

Chave de API

Toda rota /v1/* exige a chave de API do tenant no header Authorization:

Authorization: Bearer nxk_<prefixo>_<segredo>
  • A chave é emitida pela Openi para o seu tenant e aparece uma única vez, na criação. O Nexus guarda só o hash do segredo; uma chave perdida não pode ser recuperada, só substituída.
  • A chave não expira. Para trocá-la, peça uma nova chave, atualize sua aplicação e peça a revogação da anterior. Uma chave revogada passa a receber 401 na hora.
  • Um tenant pode ter várias chaves ativas, cada uma com seus escopos. Use uma chave por sistema integrado para poder revogar uma sem afetar as outras.
curl -s https://nexus-v2.openi.com.br/v1/datasets \
  -H "Authorization: Bearer $NEXUS_API_KEY"

Escopos

Os escopos são cumulativos: admin inclui write, que inclui read.

EscopoPermite
readTodas as consultas (GET) e a validação de rulesets e workflows (POST .../validate)
writeIngestões, jobs (criar, cancelar, reverter) e decisões sobre matches (confirmar, rejeitar, desfazer, match manual)
adminConfiguração: datasets, rulesets, workflows, gatilhos e webhooks (criar, alterar, apagar, testar, rotacionar segredo, reenviar entrega)

O escopo exigido por cada endpoint está na referência da API. Uma integração que só envia registros e lê resultados precisa de write; deixe admin para quem mantém a configuração.

Conferir a chave em uso

GET /v1/me devolve o tenant e os escopos da chave:

curl -s https://nexus-v2.openi.com.br/v1/me -H "Authorization: Bearer $NEXUS_API_KEY"
{
  "tenant_id": "0199a3f2-6c1e-7b40-9d2a-5f8e1c3b7a10",
  "tenant_name": "Minha empresa",
  "key_id": "0199a3f2-7d02-7c11-8e4b-2a6f9d0c5b21",
  "scopes": ["write"]
}

Falhas de autenticação

As respostas seguem o formato de erro da API.

StatusdetailCausa
401invalid api keyHeader ausente, chave malformada, segredo incorreto ou chave revogada
403api key lacks the write scopeA chave existe, mas o escopo não cobre o endpoint (o nome do escopo exigido vem na mensagem)
403tenant is suspendedO tenant está suspenso; nenhuma chave dele é aceita até a reativação
{ "title": "Unauthorized", "status": 401, "detail": "invalid api key" }

Webhooks

Os eventos que o Nexus envia para a sua aplicação não usam a chave de API. Cada entrega é assinada com o segredo do webhook (whsec_...); veja como verificar em Webhooks.

On this page