Autenticação e assinatura

Autenticação

Duas camadas, sempre juntas: o token prova que a credencial é sua; a assinatura prova que o request saiu do servidor que tem a chave privada. Uma sem a outra não move dinheiro.

Token

curl -X POST "https://auth.api.corpx.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"
{
  "access_token": "eyJraWQiOiJ…",
  "expires_in": 300,
  "token_type": "Bearer"
}

O mesmo access_token vale em todas as chamadas até expirar. Guarde-o e só peça outro quando faltar cerca de 60 segundos, ou quando a API recusar o token. Leia o expires_in da resposta — não fixe 300 no cliente.

scope é opcional. Omitir devolve um token com todos os escopos da credencial. Enviar um subconjunto (separado por espaço) restringe aquele token.

Headers em toda chamada à API

Host: https://client.api.corpx.com.

HeaderQuandoValor
AuthorizationSempreBearer {access_token}
X-Tenant-IdSempreO identificador que o banco mostrou
X-Request-TimestampSempreUnix em segundos; tolerância de 300s
X-Content-SHA256SempreSHA-256 do corpo, hex minúsculo
X-Request-SignatureSempreJWS detached — Assinatura
Idempotency-KeyPOST/PUT/PATCH que criam ou movemUUID da tentativa. Repetir devolve o original

Como montar os três headers de assinatura está no guia de assinatura. GET /v1/me também exige esses headers (é /v1/** no host assinado), mas não exige X-Tenant-Id.

Conferir o token: GET /v1/me

curl -X GET "https://client.api.corpx.com/v1/me" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Request-Signature: $SIG"

A resposta traz clientId, scopes e tenantRoles[] com os contextos em que o token vale. Para uma credencial de internet banking, sub e clientId são o mesmo valor.

O que esta credencial alcança

Ela foi emitida para uma conta. Chamadas a outra conta respondem 403 forbidden.

PodeFica com o banco / titular
Consultar saldo, extrato, dados bancáriosEmitir outra credencial
Enviar e receber PIX, TED, boleto, transferência internaCadastrar ou resetar PIN de operador
Criar webhook desta conta (accountId obrigatório)Assinar webhook de todas as contas do banco
Rotacionar as suas chaves e a sua allowlist de IPAbrir conta, backoffice, políticas do banco
Ler as travas em vigorAlterar travas do titular (PUT nas locks)

PIN e travas de horário / IP de origem são da tela do internet banking. Nas rotas de pagamento você não envia X-Transaction-Pin nem X-Acting-Document: a posse já está na chave privada e no IP da credencial.

Carência de 18 horas

A emissão devolve activeFrom 18h à frente. Até lá: 403 credential_not_yet_active. Incluir uma chave pública ou um IP novos na credencial usa a mesma carência; remover chave ou IP vale na hora. Detalhe em Chaves e IPs.