> This page is for Internet banking (beta).

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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](/ib/guias/autenticacao/chaves-e-ips).

## Por que o host é outro

| Credencial                          | Host                           | Assinatura      |
| ----------------------------------- | ------------------------------ | --------------- |
| Emitida pelo banco para a sua conta | `https://client.api.corpx.com` | Em toda chamada |
| Integrador BaaS (várias contas)     | `https://tenant.api.corpx.com` | Nã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](#testar-sem-mover-dinheiro).

Programas completos em bash, Node.js, Python e Go estão em
[Exemplos de código](/ib/guias/autenticacao/exemplos-de-assinatura).

## 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](/ib/guias/autenticacao/par-de-chaves). O resumo:

```bash
# 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:

```bash
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
```

| Campo                      | Regra                                                                                                                                                              |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `METHOD`                   | Maiúsculo: `POST`, `GET`, `PUT`, `DELETE`                                                                                                                          |
| `PATH?QUERY`               | Caminho 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 |
| `TIMESTAMP`                | O mesmo valor de `X-Request-Timestamp`: unix em **segundos**, só dígitos                                                                                           |
| `IDEMPOTENCY_KEY_OU_VAZIO` | Valor de `Idempotency-Key`; string vazia quando a request não leva o header                                                                                        |
| `X_CONTENT_SHA256`         | SHA-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](#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 é:

```json
{ "alg": "ES256", "kid": "SEU_KID", "jti": "uuid-por-requisicao" }
```

| Campo | Regra                                                                                       |
| ----- | ------------------------------------------------------------------------------------------- |
| `alg` | `ES256` (chave EC P-256) ou `PS256` (chave RSA). Tem de ser o algoritmo da chave cadastrada |
| `kid` | Obrigatório. O `kid` da chave que assinou                                                   |
| `jti` | Opcional. 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:

| `alg`   | Assinatura                                                  |
| ------- | ----------------------------------------------------------- |
| `ES256` | ECDSA P-256 + SHA-256, 64 bytes `R‖S` (veja o aviso abaixo) |
| `PS256` | RSASSA-PSS + SHA-256, MGF1 com SHA-256, salt de 32 bytes    |

```javascript
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):

```bash
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](/ib/guias/autenticacao/exemplos-de-assinatura#bash--curl--openssl).

| Header                | Obrigatório | Descrição                                |
| --------------------- | ----------- | ---------------------------------------- |
| `X-Request-Timestamp` | Sim         | Unix em segundos. Tolerância de **300s** |
| `X-Content-SHA256`    | Sim         | SHA-256 do corpo em hex minúsculo        |
| `X-Request-Signature` | Sim         | A 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](/ib/guias/autenticacao/exemplos-de-assinatura#bash--curl--openssl):

```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"
```

```json
{
  "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-----
```

| Campo              | Valor                                                              |
| ------------------ | ------------------------------------------------------------------ |
| `kid`              | `cfe8291443215153e11b76a7a533dd3c`                                 |
| `jti`              | `00000000-0000-4000-8000-000000000001`                             |
| Corpo              | `{"amount":1000}`                                                  |
| `X-Content-SHA256` | `612612d208fb618eb2b007d2a7f8d7a1cfb511532389298f1cc33322c3094bcc` |

**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](/ib/guias/autenticacao/exemplos-de-assinatura#erros-comuns).
Os códigos de cada erro estão em [Erros](/ib/guias/referencia/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](/baas/guias/comece-aqui/idempotencia).