Authentication

Dois modos de autenticação

Modo	Header	Uso
API key	X-API-Key: snxc_<env>_...	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://api.crypto.sentinexrisk.com/api/v1/vasp/screenings \
  -H "X-API-Key: snxc_live_<sua_chave>" \
  -H "Content-Type: application/json" \
  -d '{ "direction": "DEPOSIT", "asset": "BTC", "chain": "btc", "amount": 0.5, "counterparty_address": "bc1q..." }'

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

Escopos reais (superfície VASP)

Escopo	Abre
vasp:transactions:screen	POST /vasp/screenings, PATCH /vasp/screenings/:id/decision
vasp:read	GETs da superfície: screenings, alerts, wallets, deposits, trades, withdrawals, balances
vasp:customers:read / vasp:customers:write	GET / POST /vasp/customers
vasp:wallets:write	POST /vasp/wallets
vasp:deposits:write / vasp:deposits:credit	registro / transições de depósitos
vasp:trades:write / vasp:trades:execute	cotação / execução e falha de trades
vasp:withdrawals:write / vasp:withdrawals:approve	solicitação / transições de saques
vasp:webhooks:manage	POST / GET / DELETE /vasp/webhooks
vasp:compliance:read	GET /vasp/sars, GET /vasp/decripto/*

Cuidado

Princípio: solicite o escopo mínimo necessário. Escopos que não estão na tabela acima (ex.: wallets:read, vasp:write) não abrem nenhuma rota da superfície de API key; as rotas do dashboard (ex.: /wallets, /alerts sem prefixo /vasp) são JWT.

Ambientes

Keys live e de teste/sandbox são isoladas: uma key de teste não acessa a superfície live e vice-versa. O ambiente faz parte do prefixo da key (snxc_live_..., snxc_test_...).

Rate limits

A superfície VASP aplica rate limit por key, por minuto. Os headers de resposta indicam o estado atual:

X-RateLimit-Limit: <limite da sua key>
X-RateLimit-Remaining: <restante na janela>

Quando excedido, retorno 429 com header Retry-After (em segundos) e o envelope de erro codificado:

{
  "success": false,
  "error": { "code": "api_key_rate_limit_exceeded", "message": "API key rate limit exceeded" }
}

O limite default da key é definido no provisionamento; consulte o suporte para o valor contratado do seu plano.

Rotação e revogação de chaves

Pelo console (Desenvolvedores, API Keys) ou por API com JWT:

# rotacionar (a nova key é retornada UMA única vez)
curl -X POST https://api.crypto.sentinexrisk.com/api/v1/keys/<key_id>/rotate \
  -H "Authorization: Bearer <jwt>"

# revogar
curl -X DELETE https://api.crypto.sentinexrisk.com/api/v1/keys/<key_id> \
  -H "Authorization: Bearer <jwt>"

Key comprometida

Se a key foi comprometida, revogue imediatamente pelo console ou pelo DELETE /keys/:id acima e gere uma nova.

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.