Guia de chaves de API

Este guia leva uma pessoa da sua equipe do zero até a primeira chamada autenticada, nos dois ambientes: primeiro o sandbox, para testar sem efeito real, depois a produção. Todos os passos de tela estão no painel https://crypto.sentinexrisk.com.

Antes de começar

Papel na conta. Quem cria e usa chave tem o papel Desenvolvedor ou Tenant Admin. O Tenant Admin atribui o papel em Início > Usuários
Duas contas, dois ambientes. A conta de teste entra no sandbox e a conta real entra na produção. São cadastros separados. A conta de teste é criada pela Sentinex Risk: peça em suporte@sentinexrisk.com
MFA. O painel exige MFA por aplicativo autenticador (TOTP). Criar, pedir, aprovar, emitir e revogar chave exige MFA confirmado nos últimos 5 minutos. Se o painel pedir o código, confirme na janela de verificação
Para a produção. O pedido de chave de produção é aprovado por uma pessoa diferente de quem pediu, e essa pessoa precisa ter o papel Tenant Admin. Se quem pede é um Desenvolvedor, basta um Tenant Admin no tenant. Se quem pede é um Tenant Admin, é preciso outro Tenant Admin
Acesso da conta à API. A chave só funciona quando a conta do tenant está operacional e com o acesso por API liberado pela Sentinex Risk (ver Autenticação)

Parte 1: chave de sandbox

Entre no painel com a conta de teste

Abra https://crypto.sentinexrisk.com e faça o login com o e-mail da conta de teste. O ambiente é decidido pelo e-mail: no sandbox, uma faixa amarela fica fixa no topo da tela com o texto “Sandbox, dados sintéticos e efeitos externos desativados.” Se a faixa não aparece, você está na produção.
Abra a tela de chaves

No menu lateral, abra a seção Gerenciar e, sob Desenvolvedores, clique em Chaves e uso da API. A tela tem o título “Developer Dashboard” e a seção “API Keys” com a lista das suas chaves. Sob Desenvolvedores também estão o Console da API, para chamar as operações sem sair do painel, e a Referência da API.
Crie a chave

Clique em Nova API key. No formulário:
- Nome: o campo vem com um nome sugerido. Troque por um nome que diga onde a chave vai ficar, por exemplo “Integração homologação”
- Ambiente: no sandbox, a única opção é “Sandbox (sandbox)”
- Escopos: a caixa “Todos os escopos do KYT” já vem marcada e cobre todas as operações do contrato. Para dar menos acesso, desmarque o que não for usar
- Limite de chamadas por minuto: deixe em branco para o padrão de 60 por minuto, ou informe um valor de 1 a 10.000
Clique em Criar key. Se o painel pedir o MFA, confirme o código na janela de verificação e depois confirme a criação de novo. Não existe campo de validade no formulário: a chave de sandbox vale 29 dias e 23 horas.
Copie a chave agora

A janela “Copie sua API key agora” mostra a chave completa uma única vez. Clique em Copiar key e guarde o valor num cofre de segredos ou numa variável de ambiente. Depois de fechar a janela, o painel só mostra o prefixo. Se você perder o valor, revogue a chave e crie outra.
Faça a primeira chamada com curl

Guarde a chave numa variável e confirme primeiro que a base é a do sandbox:
Janela do terminal
```
export SENTINEX_API_KEY='snxc_sand_<sua_chave>'
export SENTINEX_BASE_URL='https://sandbox.api.crypto.sentinexrisk.com/api/v1'

# o header X-Sentinex-Environment: sandbox precisa aparecer
curl -i "$SENTINEX_BASE_URL/health"
```
Depois, uma leitura que confere a chave, o ambiente e o acesso da conta sem gravar nada (escopo vasp:read):
Janela do terminal
```
curl "$SENTINEX_BASE_URL/vasp/alerts?limit=1" \
  -H "X-API-Key: $SENTINEX_API_KEY"
```
Resposta esperada em um tenant sem alertas:
```
{
  "success": true,
  "data": [],
  "pagination": { "total": 0, "limit": 1, "offset": 0 }
}
```
Se vier 401 com invalid_api_key, a chave está errada, expirada, revogada ou é de outro ambiente: confira se ela começa com snxc_sand_ e se a base é a do sandbox. Se vier 403 com api_key_environment_not_allowed, a plataforma reconheceu uma chave registrada para outro ambiente.
Analise uma transação com uma fixture

No sandbox, a contraparte precisa ser um endereço do catálogo de fixtures (ver Homologação e testes). Este exemplo usa a fixture de baixo risco e exige o escopo vasp:transactions:screen:
Janela do terminal
```
curl -X POST "$SENTINEX_BASE_URL/vasp/screenings" \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "client_transaction_id": "teste-0001",
    "customer_ref": "cliente-teste-42",
    "direction": "WITHDRAWAL",
    "asset": "ETH",
    "chain": "ethereum",
    "counterparty_address": "0x7eae68ba864d7e60463ca6842c53f1b20ecfb1a2",
    "amount": 1.5,
    "fiat_value_brl": 7500.5
  }'
```
A resposta traz recommendation igual a ALLOW, risk_level igual a LOW e risk_score igual a 5. Troque o endereço por 0x4f6429a9dfcd41a13f20d5f96d0facd04847e691 para ver o caminho de DENY por sanção sintética. Um endereço fora do catálogo responde 422 com SANDBOX_FIXTURE_NOT_SUPPORTED.

Registre a sua decisão

Use o screening_id da resposta anterior. A decisão é gravada uma única vez:

curl -X PATCH "$SENTINEX_BASE_URL/vasp/screenings/<screening_id>/client-decision" \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_decision": {
      "operational_action": "ALLOW",
      "suspicion_outcome": "NOT_SUSPICIOUS",
      "rationale": "Teste de integração no sandbox."
    }
  }'

Se preferir não usar o terminal, o Console da API do painel envia as mesmas chamadas, e no sandbox ele lista as fixtures na própria tela.

Parte 2: chave de produção

A chave de produção não nasce na hora. Ela passa por três etapas, e cada uma é feita por uma pessoa e por um motivo: quem pede, quem aprova e quem emite.

Entre no painel com a conta de produção

Faça o login com o e-mail da conta real. Não há faixa amarela no topo. Confirme também que você é um Desenvolvedor ou um Tenant Admin do tenant.
Peça a chave

Em Gerenciar > Chaves e uso da API, clique em Nova API key. Na produção, a única opção de ambiente é “Produção (live)”. Preencha nome, escopos e limite como no sandbox e clique em Criar key.

O painel não mostra chave nenhuma nesse momento. Ele registra o pedido e avisa: “Solicitação live registrada. A chave só poderá ser emitida após aprovação por outro Tenant Admin.” A validade da chave de produção é de até 90 dias (89 dias e 23 horas quando nenhuma data é informada).
Outro Tenant Admin aprova

A pessoa que aprova entra na mesma tela, Gerenciar > Chaves e uso da API, e abre a seção Pedidos de chave live. Ela vê os pedidos do tenant, com escopos, endereços IP, limite e validade de cada um. Nos pedidos de outras pessoas aparecem os botões Aprovar e Rejeitar. No pedido que ela mesma abriu aparece só o aviso “Você abriu este pedido. Outro Tenant Admin precisa aprovar ou rejeitar.”

Ao clicar em Aprovar, abre-se uma janela com o resumo do pedido. Ela informa o motivo, de 3 a 512 caracteres, clica em Aprovar pedido e confirma o MFA. A aprovação vale por 24 horas. Quem aprova nunca recebe o segredo da chave.
Quem pediu emite a chave

Quem abriu o pedido volta à seção Pedidos de chave live. O pedido agora aparece como “Aprovado, aguardando emissão”, com o prazo da aprovação, e o botão Emitir chave fica disponível só para essa pessoa. Ao clicar, o painel avisa que o segredo aparece uma única vez; confirme em Emitir e mostrar a chave e valide o MFA.

A janela “Copie sua API key agora” mostra a chave snxc_live_... completa. Copie e guarde num cofre de segredos, como no sandbox. A emissão consome a aprovação: não há segunda exibição, e uma repetição da emissão devolve apenas o identificador da chave, sem o segredo. Se a aprovação passar das 24 horas sem emissão, a emissão responde 409 com LIVE_KEY_APPROVAL_REQUIRED e o pedido precisa de nova decisão ou de um novo pedido.
Faça a primeira chamada em produção

Comece por uma leitura, que não grava nada:
Janela do terminal
```
export SENTINEX_API_KEY='snxc_live_<sua_chave>'
export SENTINEX_BASE_URL='https://crypto-api.sentinexrisk.com/api/v1'

curl "$SENTINEX_BASE_URL/vasp/alerts?limit=1" \
  -H "X-API-Key: $SENTINEX_API_KEY"
```
Na produção, uma análise de verdade é uma análise real: ver Homologação e testes antes de chamar POST /vasp/screenings.

Depois da primeira chave

Rotação. No sandbox, a pessoa que criou a chave a rotaciona na hora e recebe a substituta com o segredo na tela. Na produção, a rotação é um novo pedido, com a mesma aprovação e a mesma emissão. Nos dois casos a chave anterior segue válida durante a sobreposição, de 15 minutos a 24 horas (24 horas por padrão), para você trocar a chave em cada consumidor sem derrubar a integração
Revogação. Revogar invalida a chave na chamada seguinte e não tem volta: para voltar, crie outra. O Desenvolvedor revoga as próprias chaves, e o Tenant Admin revoga qualquer chave do tenant
Quem vê o quê. O Desenvolvedor vê só as próprias chaves e os próprios pedidos. O Tenant Admin vê as chaves e os pedidos do tenant inteiro

Erros comuns

O que aparece	O que significa	O que fazer
`401` com `invalid_api_key`, ou `403` com `api_key_environment_not_allowed`, ao chamar a API	A chave é de outro ambiente: `snxc_live_` no host do sandbox, ou `snxc_sand_` no host de produção	Use a chave e a base do mesmo ambiente
`400` com `api_key_environment_not_allowed` ao criar a chave	O ambiente pedido não é servido por esta instalação	Crie a chave no painel do ambiente certo
`403` com `MFA_STEP_UP_REQUIRED`	O MFA não foi confirmado nos últimos 5 minutos	Confirme o MFA e repita a ação
`403` com `KEY_REQUEST_SELF_APPROVAL_FORBIDDEN`	Quem pediu tentou aprovar o próprio pedido	Peça a outro Tenant Admin
`409` com `LIVE_KEY_APPROVAL_REQUIRED`	Chave de produção não nasce na hora, ou a aprovação deixou de valer	Abra um pedido, ou peça nova aprovação
`409` com `KEY_REQUEST_STALE`	O pedido mudou depois da sua leitura	Atualize a lista e decida de novo
`422` com `SANDBOX_FIXTURE_NOT_SUPPORTED`	O endereço da contraparte não é uma fixture do sandbox	Use um endereço da tabela de Homologação e testes
`401` com `invalid_api_key`	Chave desconhecida, expirada ou revogada (ou de outro ambiente, como na primeira linha)	Confira o valor ou crie outra chave
`402` ou `403` com `TRIAL_EXPIRED`, `TENANT_NOT_OPERATIONAL` ou `API_ACCESS_DISABLED`	A conta do tenant não está liberada para a API	Fale com suporte@sentinexrisk.com

Os códigos de acesso da conta e de limite de requisições estão em Autenticação e em Erros e códigos.