Authentication

Dois modos de autenticação

Modo	Header	Uso
API key	X-API-Key: snxc_<ambiente>_...	Integração máquina-a-máquina na superfície /api/v1/vasp/*.
JWT RS256	Authorization: Bearer <access_token>	Console web, operações humanas com RBAC e MFA.

A API key identifica o tenant e carrega os escopos. Não existe header X-Tenant-ID: o backend nunca resolve tenant por header (anti-spoof); qualquer tutorial que peça esse header está desatualizado.

curl -X POST https://crypto-api.sentinexrisk.com/api/v1/vasp/screenings \
  -H "X-API-Key: snxc_live_<sua_chave>" \
  -H "Content-Type: application/json" \
  -d '{ "direction": "DEPOSIT", "asset": "USDT", "chain": "ethereum", "amount": 1500.25, "counterparty_address": "0x1111111111111111111111111111111111111111" }'

Esta chamada usa a base de produção. No sandbox, a base é https://sandbox.api.crypto.sentinexrisk.com/api/v1, a chave começa com snxc_sand_ e a contraparte precisa ser uma fixture (ver Homologação e testes).

O backend também aceita Authorization: Bearer snxc_... como fallback para a API key, mas X-API-Key é o modo canônico.

Escopos da superfície /vasp

Cada operação do contrato do cliente exige um escopo. Chave sem o escopo recebe 403 com error.code: "insufficient_scope".

Escopo	Operações do contrato
vasp:transactions:screen	POST /vasp/screenings, PATCH /vasp/screenings/{id}/client-decision, PATCH /vasp/screenings/{id}/tx-hash (e o alias obsoleto /decision), POST /vasp/kyt-report
vasp:read	GET /vasp/screenings/{id}, GET /vasp/alerts, GET /vasp/wallets/{id}
vasp:customers:write	POST /vasp/customers, POST /vasp/customers/batch
vasp:customers:read	GET /vasp/customers, GET /vasp/customers/{id}, POST /vasp/customers/search
vasp:wallets:write	POST /vasp/wallets, PATCH /vasp/wallets/{id}, DELETE /vasp/wallets/{id}
vasp:webhooks:manage	POST e GET /vasp/webhooks, DELETE /vasp/webhooks/{id}, POST /vasp/webhooks/{id}/test
vasp:compliance:read	GET /vasp/sars, GET /vasp/sars/{id}, GET /vasp/decripto/monthly, GET /vasp/decripto/annual

As escritas de KYT (POST /vasp/screenings, a decisão do cliente e o laudo) também exigem o módulo de KYT habilitado no tenant; sem ele, a resposta é 403 com code: "MODULE_NOT_ENABLED".

Cuidado

Princípio: solicite o escopo mínimo necessário. Escopos que não estão na tabela acima (por exemplo wallets:read ou vasp:write) não abrem nenhuma operação do contrato. As rotas do painel, sem o prefixo /vasp, usam sessão de usuário e não aceitam chave de API.

Ambiente da chave

O ambiente faz parte da chave e aparece no prefixo. Cada ambiente é uma instalação separada e só aceita o prefixo dele:

Prefixo	Ambiente	Base da API	Validade máxima
snxc_sand_	Sandbox	https://sandbox.api.crypto.sentinexrisk.com/api/v1	30 dias
snxc_live_	Produção	https://crypto-api.sentinexrisk.com/api/v1	90 dias

O prefixo snxc_test_ existe no formato, mas nenhum dos dois ambientes o aceita. Chaves emitidas a partir da 2.16.0 têm o formato snxc_<ambiente>_<identificador>_<segredo> (107 caracteres no total); chaves anteriores, snxc_<ambiente>_<hex>, valem até a expiração ou a revogação. Trate a chave como texto opaco.

Cada ambiente guarda só as próprias chaves, então uma chave de outro ambiente não autentica, mesmo com os escopos certos. A resposta é 401 com error.code: "invalid_api_key" quando o ambiente não conhece a chave, e 403 com error.code: "api_key_environment_not_allowed" quando o prefixo identifica outro ambiente, antes de autenticar, ou quando o ambiente registrado da chave é recusado. Se a plataforma não conseguir informar o ambiente da chave verificada, a resposta é 403 com api_key_environment_required. Os dois ambientes estão descritos em Homologação e testes.

Como a chave nasce

A chave é sempre gerada pelo servidor. O corpo da criação que envia um segredo próprio (full_key) é recusado com 400 e api_key_secret_must_be_server_generated. O segredo aparece uma única vez, na resposta que emite a chave, e o servidor guarda só um verificador dele.

	Sandbox	Produção
Emissão	Imediata, por quem cria	Em três etapas: pedido, aprovação e emissão
Quem pode pedir	Desenvolvedor e Tenant Admin	Desenvolvedor e Tenant Admin
Quem aprova	Ninguém	Um Tenant Admin diferente de quem pediu. Autoaprovação é recusada com 403 e KEY_REQUEST_SELF_APPROVAL_FORBIDDEN, no servidor e no banco
Quem emite e vê o segredo	Quem criou	Só quem pediu. Quem aprova nunca recebe o segredo
MFA	Confirmado nos últimos 5 minutos	Confirmado nos últimos 5 minutos, em cada etapa
Validade da aprovação	Não se aplica	24 horas
Validade da chave	Até 30 dias (29 dias e 23 horas sem data informada)	Até 90 dias (89 dias e 23 horas sem data informada)

O pedido de produção guarda nome, escopos, endereços IP permitidos, limite, validade e, na rotação, a chave anterior e a sobreposição. Ele é imutável: mudar qualquer um desses itens exige outro pedido. Um pedido que mudou entre a leitura e a decisão responde 409 com KEY_REQUEST_STALE. Tentar criar chave de produção pela via imediata responde 409 com LIVE_KEY_APPROVAL_REQUIRED. O passo a passo, com as telas, está no Guia de chaves de API.

Acesso da conta

Depois da chave, toda requisição passa pelo estado da conta do tenant. Só segue conta em estado operacional com o acesso por API liberado. Recusas: 402 com TRIAL_EXPIRED, 403 com TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED ou TENANT_ACCESS_DENIED, e 503 com TENANT_ACCESS_STATE_UNAVAILABLE. O código vem no campo code, ao lado de error. Desligar o acesso por API não revoga a chave: vale a partir da requisição seguinte.

Limite por chave

O limite é por chave e por minuto, definido na criação da chave (rate_limit_per_min, de 1 a 10.000). Chave criada sem esse campo usa 60 por minuto. As respostas trazem X-RateLimit-Limit e X-RateLimit-Remaining; ao estourar, 429 com Retry-After e error.code: "api_key_rate_limit_exceeded". Os limites por IP, aplicados antes da chave, estão em Limites de requisição.

Rotação e revogação de chaves

Rotação e revogação são feitas no painel, em Desenvolvedores > Chaves e uso da API. O servidor guarda só o verificador da chave: copie a nova na hora, porque ela não pode ser recuperada depois.

• Rotação. A chave substituta herda nome, escopos, endereços IP e limite da anterior. A anterior continua autenticando durante a sobreposição, que pode ser de 15 minutos, 1 hora, 4 horas, 12 horas ou 24 horas (24 horas por padrão), para você trocar a chave em cada consumidor. No sandbox, a pessoa que criou a chave rotaciona na hora. Na produção, a rotação é um pedido do tipo rotação, com a mesma aprovação e a mesma emissão de uma chave nova
• Revogação. Invalida a chave na requisição seguinte, prevalece sobre qualquer sobreposição em andamento e não tem volta: para voltar, crie outra chave. O Desenvolvedor revoga as próprias chaves e o Tenant Admin revoga qualquer chave do tenant. Exige MFA confirmado nos últimos 5 minutos e um motivo, que fica na trilha de auditoria

Chave comprometida

Se a chave foi comprometida, revogue imediatamente no painel e crie outra.

CSRF protection

Mutações (POST/PUT/PATCH/DELETE) em rotas com sessão de browser (JWT + cookie) exigem header X-CSRF-Token. Para clientes server-to-server com API key, CSRF não se aplica.

MFA para o console

O acesso ao console web (crypto.sentinexrisk.com) exige MFA TOTP. API keys não usam MFA: a autenticação é pela posse da chave, por isso guarde-a em um cofre de segredos e nunca a exponha em frontend ou repositório.

Limite do produto

O contrato desta integração é KYT. KYC próprio e eventos kyc.* não estão disponíveis. Nas rotas B2B /api/v1/kyc/cases, o gate retorna 403 PRODUCT_MODULE_DISABLED após autenticação e acesso da conta. Ter escopo de KYC não habilita produto ausente. Contratação e instalação habilitada são requisitos separados, sem data prometida. O catálogo GET /api/v1/rules é consultado com sessão do painel, fora da API key B2B.