Skip to navigation

Assinatura de requisição

Toda chamada a https://client.api.corpx.com/v1/** leva, além do token, uma assinatura feita com a chave privada que ficou no seu servidor.

O token OAuth é um portador: quem o copia do log ou do proxy pode usá-lo até expirar. A assinatura resolve isso porque a chave privada não viaja. Um token vazado sem ela não move dinheiro.

Rotação de chaves e allowlist de IP estão em Chaves e IPs.

Por que o host é outro

CredencialHostAssinatura
Emitida pelo banco para a sua contahttps://client.api.corpx.comEm toda chamada
Integrador BaaS (várias contas)https://tenant.api.corpx.comNão

Usar a credencial da conta no host antigo devolve 403 signed_host_required. O host antigo guarda a decisão de autorização em cache por 300s; uma decisão em cache não pode depender da assinatura daquela requisição. O host assinado verifica a cada chamada.

O contrário também vale: o host assinado só expõe /v1/** e recusa qualquer request sem um dos quatro headers (Authorization, X-Request-Timestamp, X-Content-SHA256, X-Request-Signature) antes de olhar o token, com 401 e sem corpo.

A borda que verifica a assinatura não devolve motivo: uma chamada real recusada por token, credencial, IP, relógio ou assinatura é um 403 sem corpo. O motivo está em Testar sem mover dinheiro.

Programas completos em bash, Node.js, Python e Go estão em Exemplos de código.

Passo 1: o par de chaves

O passo a passo — gerar, extrair a pública, conferir a impressão digital e cadastrar no internet banking — está em Gerar o par de chaves. O resumo:

# Privada: FICA NO SEU SERVIDOR. Nunca envie este arquivo.
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out corpx-signing.key
# Pública: é esta que vai para a tela de credenciais (ou para a rotação).
openssl pkey -in corpx-signing.key -pubout -out corpx-signing.pub

EC P-256 assina com ES256; RSA de 2048 bits ou mais, com PS256. A pública vai como PEM -----BEGIN PUBLIC KEY-----. Mandar a privada devolve 422 invalid_public_key — trate essa chave como comprometida e gere outra.

O kid

Cada chave recebe um kid derivado do SHA-256 do DER da chave pública, truncado em 16 bytes (32 hex). Derivado — e não sorteado — para você conferir offline que cadastrou a chave certa:

openssl pkey -pubin -in corpx-signing.pub -outform DER | openssl dgst -sha256 -r | cut -c1-32

O valor tem de ser igual ao kid que a API devolveu. A impressão digital que a tela do internet banking mostra é o mesmo hash inteiro, com : entre os bytes.

Passo 2: a string canônica

Cinco campos, nesta ordem, separados por \n (LF, não CRLF):

METHOD \n PATH?QUERY \n TIMESTAMP \n IDEMPOTENCY_KEY_OU_VAZIO \n X_CONTENT_SHA256
CampoRegra
METHODMaiúsculo: POST, GET, PUT, DELETE
PATH?QUERYCaminho como enviado, byte a byte, com a query se houver — mesma ordem e mesmo encoding da URL. Sem host. Chave codificada no path (%40, %2B) entra codificada
TIMESTAMPO mesmo valor de X-Request-Timestamp: unix em segundos, só dígitos
IDEMPOTENCY_KEY_OU_VAZIOValor de Idempotency-Key; string vazia quando a request não leva o header
X_CONTENT_SHA256SHA-256 dos bytes do corpo em hex minúsculo. Corpo vazio = hash do vazio, não string vazia

Exemplo para um POST com corpo {"amount":1000} (os mesmos valores do vetor de teste):

POST
/v1/accounts/acc-123/pix/payments
1789412400
4f1e3b7a-9d2c-4a11-8f55-2b0c6a7d1e90
612612d208fb618eb2b007d2a7f8d7a1cfb511532389298f1cc33322c3094bcc

Num GET com query, a linha do path leva a query e a da chave fica vazia:

GET
/v1/accounts/acc-123/statement?startDate=2026-10-01&endDate=2026-10-15
1789412400
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

O hash do corpo vazio é sempre e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Use-o em GET e DELETE.

Exemplo para consultar uma chave de e-mail — GET, sem Idempotency-Key (a linha fica vazia) e com o hash do corpo vazio. O @ da chave vai codificado, igual ao path da requisição:

GET
/v1/accounts/acc-123/pix/key/fulano%40exemplo.com
1789412400
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Passo 3: assinar

A assinatura é uma JWS compacta com payload destacado (RFC 7797): <protected>..<signature> — note os dois pontos seguidos.

O header protegido é:

{ "alg": "ES256", "kid": "SEU_KID", "jti": "uuid-por-requisicao" }
CampoRegra
algES256 (chave EC P-256) ou PS256 (chave RSA). Tem de ser o algoritmo da chave cadastrada
kidObrigatório. O kid da chave que assinou
jtiOpcional. Serve para correlacionar log

O que é assinado é base64url(protected) + "." + base64url(stringCanônica) — base64url sem padding (=), nos dois pedaços e na assinatura. O hash é sempre SHA-256:

algAssinatura
ES256ECDSA P-256 + SHA-256, 64 bytes R‖S (veja o aviso abaixo)
PS256RSASSA-PSS + SHA-256, MGF1 com SHA-256, salt de 32 bytes
const crypto = require('node:crypto');
function sign(privateKeyPem, kid, canonical) {
const b64 = (buf) => Buffer.from(buf).toString('base64url');
const protected_ = b64(JSON.stringify({ alg: 'ES256', kid, jti: crypto.randomUUID() }));
const input = `${protected_}.${b64(canonical)}`;
const signature = crypto.sign('sha256', Buffer.from(input), {
key: privateKeyPem,
// dsaEncoding é obrigatório: sem ele o Node emite DER e a API recusa.
dsaEncoding: 'ieee-p1363',
});
return `${protected_}..${b64(signature)}`;
}
function contentSha256(body) {
return require('node:crypto').createHash('sha256').update(body).digest('hex');
}
function canonicalString({ method, path, timestamp, idempotencyKey = '', body = '' }) {
return [method, path, String(timestamp), idempotencyKey, contentSha256(body)].join('\n');
}
ES256 é R\|\|S, não DER

A assinatura tem de ter exatamente 64 bytes (R e S de 32 bytes cada). A maioria das bibliotecas emite DER por padrão e a API recusa com request_signature_invalid. Em Node é dsaEncoding: 'ieee-p1363'; em Go, monte R||S a partir de ecdsa.Sign; em Python, use utils.decode_dss_signature e concatene.

Passo 4: enviar

O corpo enviado tem de ser byte a byte o que entrou no hash. Guarde-o numa variável e mande com --data-binary (-d @arquivo remove as quebras de linha do arquivo, e o hash deixa de bater):

BODY='{"amount":100.00,"keyType":"CPF","key":"12345678901"}'
# TS, SHA e SIG calculados sobre POST, o path abaixo, $IDEM e $BODY
curl -X POST "https://client.api.corpx.com/v1/accounts/$ACCOUNT_ID/pix/out" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Idempotency-Key: $IDEM" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: $SHA" \
-H "X-Request-Signature: $SIG" \
-H "Content-Type: application/json" \
--data-binary "$BODY"

A função sign que calcula TS, SHA e SIG com openssl está em Exemplos de código.

HeaderObrigatórioDescrição
X-Request-TimestampSimUnix em segundos. Tolerância de 300s
X-Content-SHA256SimSHA-256 do corpo em hex minúsculo
X-Request-SignatureSimA JWS detached do passo 3

O hash do corpo viaja no header — a borda verifica a assinatura sem reler o corpo. Quem confere que o corpo recebido bate com o hash é a aplicação, depois da borda. Divergência devolve 400 body_hash_mismatch.

Testar sem mover dinheiro

POST /v1/security/signature/verify devolve a string canônica que nós montamos, o hash que esperávamos e o resultado. Sempre responde 200 (exceto corpo malformado), inclusive quando a assinatura é inválida: um 401 aqui se misturaria com “token expirado”.

É a única rota do host assinado que responde com a assinatura errada, com o relógio fora da janela ou com a credencial ainda na carência de 18h. Para chegar nela você ainda precisa de token válido, credencial ativa e IP na allowlist; sem isso, 403 sem corpo como em qualquer rota.

Quando uma chamada real voltou 403 sem corpo, repita-a aqui: mesmos headers, e no corpo o method, o path e o body que você tinha assinado. A resposta traz edgeReason com o que a borda recusou e, se a credencial ainda não vale, activeFrom com a hora em que passa a valer.

São duas assinaturas: a do PIX que você quer testar (vai no corpo, não é executado) e a da própria chamada ao autoteste, que também é /v1/**. O timestamp do PIX passa pela mesma janela de 300s, então assine na hora. Com a função sign dos exemplos em bash:

# 1. Assina o PIX que seria enviado (não é enviado)
PIX_PATH="/v1/accounts/$ACCOUNT_ID/pix/out"
PIX_BODY='{"amount":100.00,"keyType":"CPF","key":"12345678901"}'
IDEM=$(uuidgen | tr 'A-Z' 'a-z')
sign POST "$PIX_PATH" "$PIX_BODY" "$IDEM"
VERIFY_BODY=$(jq -nc --arg path "$PIX_PATH" --arg ts "$TS" --arg idem "$IDEM" \
--arg body "$PIX_BODY" --arg sig "$SIG" \
'{method: "POST", path: $path, timestamp: $ts, idempotencyKey: $idem, body: $body, signature: $sig}')
# 2. Assina e envia a chamada ao autoteste
sign POST /v1/security/signature/verify "$VERIFY_BODY" ""
curl -X POST "https://client.api.corpx.com/v1/security/signature/verify" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: $SHA" \
-H "X-Request-Signature: $SIG" \
-H "Content-Type: application/json" \
--data-binary "$VERIFY_BODY"
{
"valid": true,
"kid": "9f2a...",
"alg": "ES256",
"canonicalString": "POST\n/v1/accounts/acc-123/pix/out\n1789412400\n...",
"expectedContentSha256": "8f0c60fb...",
"signedHost": "client.api.corpx.com",
"maxSkewSeconds": 300,
"usableKids": ["9f2a..."]
}

Quando valid é false, reason traz o mesmo código da requisição real. Compare canonicalString caractere a caractere. edgeReason aparece quando a borda teria recusado esta mesma chamada (request_timestamp_skew, request_signature_invalid, unknown_kid, credential_not_yet_active); activeFrom aparece enquanto a credencial está na carência.

Vetor de teste

Use estes valores para validar a implementação offline, sem credencial. A JWS abaixo confere contra a chave pública com dsaEncoding: 'ieee-p1363'.

Chave pública (SPKI PEM):

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE6VuQL7n18jc/8dHENPXeHZrdCVPu
q2j496awbvsDhxWTVj3hBScPI9MioPmlfS9nNUo9MJhTDNMfVRUALXXrfg==
-----END PUBLIC KEY-----
CampoValor
kidcfe8291443215153e11b76a7a533dd3c
jti00000000-0000-4000-8000-000000000001
Corpo{"amount":1000}
X-Content-SHA256612612d208fb618eb2b007d2a7f8d7a1cfb511532389298f1cc33322c3094bcc

String canônica (LF entre as linhas, sem CRLF, sem newline no fim):

POST
/v1/accounts/acc-123/pix/payments
1789412400
4f1e3b7a-9d2c-4a11-8f55-2b0c6a7d1e90
612612d208fb618eb2b007d2a7f8d7a1cfb511532389298f1cc33322c3094bcc

JWS:

eyJhbGciOiJFUzI1NiIsImtpZCI6ImNmZTgyOTE0NDMyMTUxNTNlMTFiNzZhN2E1MzNkZDNjIiwianRpIjoiMDAwMDAwMDAtMDAwMC00MDAwLTgwMDAtMDAwMDAwMDAwMDAxIn0..hN37T9veyWLyXnEvXqnPwFIsD1GzgKfoY_bHzkc3rx3-MZCNhVaIVq1W_P77g8Dfw6IJ09wBddu6bhNQkGulvQ

A assinatura tem 64 bytes (R||S). Se a sua biblioteca emitir DER, o resultado não bate.

Erros mais comuns

  1. CRLF em vez de LF na string canônica.
  2. Path sem a query string que foi no request.
  3. Path assinado numa forma e enviado em outra: chave com @ ou + codificada na URL (%40, %2B) e crua na string canônica, ou o contrário (request_signature_invalid). Biblioteca HTTP que normaliza a URL ao enviar causa o mesmo erro.
  4. Timestamp em milissegundos.
  5. Hash do vazio como string vazia, em vez do SHA-256 de zero bytes.
  6. Corpo reserializado depois do hash (400 body_hash_mismatch).
  7. Assinatura ES256 em DER (request_signature_invalid).
  8. Relógio fora de 300s (request_timestamp_skew) — configure NTP.
  9. kid ainda na carência de 18h ou já aposentado (unknown_kid).
  10. Credencial no host errado (signed_host_required).

Os itens 1 a 5 e 7 a 9 são recusados já na borda com 403 sem código no corpo: a borda não diz qual regra falhou. Use o autoteste acima e a tabela de diagnóstico. Os códigos de cada erro estão em Erros.

Replay

Uma requisição assinada pode ser repetida dentro da janela de 300s. Isso é aceito de propósito:

  • Em mutação, Idempotency-Key é obrigatória e entra na string canônica — ela é o nonce. Repetir devolve o resultado da original.
  • Em leitura, repetir devolve a mesma leitura.

Detalhe: Idempotência.