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
401na 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.
| Escopo | Permite |
|---|---|
read | Todas as consultas (GET) e a validação de rulesets e workflows (POST .../validate) |
write | Ingestões, jobs (criar, cancelar, reverter) e decisões sobre matches (confirmar, rejeitar, desfazer, match manual) |
admin | Configuraçã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.
| Status | detail | Causa |
|---|---|---|
401 | invalid api key | Header ausente, chave malformada, segredo incorreto ou chave revogada |
403 | api key lacks the write scope | A chave existe, mas o escopo não cobre o endpoint (o nome do escopo exigido vem na mensagem) |
403 | tenant is suspended | O 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.

