> 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.

# Gerar o par de chaves

A credencial da sua conta assina toda requisição com um par de chaves que
**você** gera. A chave privada fica no servidor que chama a API; a pública
vai para a tela de credenciais do internet banking. O banco e a CorpX nunca
veem a privada — e nunca vão pedir por ela.

Você vai precisar de um terminal com `openssl` (OpenSSL 1.1.1+, OpenSSL 3 ou
o LibreSSL que vem no macOS).

## O que é aceito

| Algoritmo   | Chave                    | `alg` na assinatura | Quando usar                                                                 |
| ----------- | ------------------------ | ------------------- | --------------------------------------------------------------------------- |
| ECDSA P-256 | EC `prime256v1` (P-256)  | `ES256`             | **Recomendado.** Chave e assinatura curtas, suportado em qualquer linguagem |
| RSA-PSS     | RSA de 2048 bits ou mais | `PS256`             | Quando a chave já vive num HSM/KMS que só faz RSA                           |

A pública é enviada como **PEM SPKI**: um bloco que começa com
`-----BEGIN PUBLIC KEY-----`. O algoritmo é deduzido do tipo da chave; você
não escolhe nada na tela.

São recusados: outras curvas (P-384, secp256k1, Ed25519), RSA abaixo de
2048 bits, `-----BEGIN RSA PUBLIC KEY-----` (PKCS#1), certificado
(`BEGIN CERTIFICATE`), JWK, chave OpenSSH (`ssh-rsa …`) e — o erro mais
caro — qualquer PEM de chave **privada**.

#### Gere a chave privada

No servidor que vai chamar a API (não no seu notebook, se puder evitar):

```bash
umask 077
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out corpx-signing.key
```

`umask 077` faz o arquivo nascer legível só pelo seu usuário. Se o seu
`openssl` não tiver `genpkey`, este comando gera uma chave equivalente:

```bash
openssl ecparam -genkey -name prime256v1 -noout -out corpx-signing.key
```

Para RSA (`PS256`):

```bash
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out corpx-signing.key
```

#### Extraia a chave pública

```bash
openssl pkey -in corpx-signing.key -pubout -out corpx-signing.pub
cat corpx-signing.pub
```

```text
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE6VuQL7n18jc/8dHENPXeHZrdCVPu
q2j496awbvsDhxWTVj3hBScPI9MioPmlfS9nNUo9MJhTDNMfVRUALXXrfg==
-----END PUBLIC KEY-----
```

Uma chave EC tem essas 4 linhas; uma RSA de 3072 bits, cerca de 11. Para
conferir o tipo:

```bash
openssl pkey -pubin -in corpx-signing.pub -noout -text | grep -E 'Public-Key|ASN1 OID'
# EC:  Public-Key: (256 bit) / ASN1 OID: prime256v1
# RSA: Public-Key: (3072 bit)
```

Se a sua chave está em HSM/KMS, exporte a pública em PEM (SPKI). Se ela
saiu como `BEGIN RSA PUBLIC KEY`, converta:

```bash
openssl rsa -RSAPublicKey_in -in chave-pkcs1.pub -pubout -out corpx-signing.pub
```

#### Anote a impressão digital e o kid

A impressão digital é o SHA-256 do DER da chave pública. É ela que a tela do
internet banking mostra quando você cola a chave:

```bash
openssl pkey -pubin -in corpx-signing.pub -outform DER | openssl dgst -sha256 -c
# SHA2-256(stdin)= cf:e8:29:14:43:21:51:53:e1:1b:76:a7:a5:33:dd:3c:3d:fc:d3:ab:23:b9:d2:96:f3:5e:44:b9:6c:bc:63:7c
```

(As saídas de exemplo nesta página são da chave pública do
[vetor de teste](/ib/guias/autenticacao/vetores-de-teste).)

O `kid` — o identificador que vai em toda assinatura — são os primeiros 16
bytes desse mesmo hash, em hex, sem os `:`:

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

O `kid` é derivado, não sorteado: você recalcula offline e confere que
cadastrou a chave certa. Os [exemplos de código](/ib/guias/autenticacao/exemplos-de-assinatura)
calculam o `kid` a partir da chave privada, então não há o que configurar.

#### Cadastre a pública no internet banking

Quem emite a credencial é o titular da conta (ou um operador com permissão
para isso), na tela **Credenciais de API** do internet banking:

1. Cadastre antes o IP de saída do servidor em **IPs permitidos**. Sem pelo
   menos um IP a credencial não é emitida.
2. Clique em **Emitir credencial de API**, dê um nome (ex.: `ERP produção`)
   e marque os escopos.
3. Em **Chave pública (PEM)**, cole o conteúdo **inteiro** de
   `corpx-signing.pub`, com as linhas `BEGIN` e `END`.
4. Confira se a impressão digital que aparece abaixo do campo é a mesma
   do passo 3.
5. Emita. A tela mostra `client_id`, `client_secret` e `token_url` **uma
   única vez**: guarde o `client_secret` no seu cofre de segredos antes de
   fechar.

A credencial nasce em carência: ela passa a valer 18 horas depois da
emissão. Até lá as chamadas respondem `403`. Veja
[Autenticação](/ib/guias/autenticacao/oauth2#carência-de-18-horas).

> **Colou a chave privada?**
>
> A tela recusa um PEM de chave privada, mas trate a chave como comprometida
> mesmo assim: ela passou por clipboard, navegador e talvez por um chat.
> Gere outro par e cadastre a nova pública.

## Confira que a privada e a pública são o mesmo par

Antes de cadastrar, e sempre que trocar de servidor:

```bash
diff <(openssl pkey -in corpx-signing.key -pubout) corpx-signing.pub && echo "mesmo par"
```

## Guardar a chave privada

* **Nunca** envie a privada a ninguém — nem ao banco, nem ao suporte da
  CorpX. Ninguém do nosso lado precisa dela.
* Não a coloque em repositório, imagem de container, variável de CI
  exposta em log ou ticket. Prefira um cofre (AWS Secrets Manager, GCP
  Secret Manager, HashiCorp Vault) ou, melhor, um KMS/HSM que assina sem
  exportar a chave.
* No disco, permissão `600` e dono igual ao usuário do serviço:
  `chmod 600 corpx-signing.key`.
* Um par por ambiente. Homologação e produção com a mesma chave fazem um
  vazamento em homologação valer em produção.

## Rotacionar

A credencial aceita mais de uma chave pública ao mesmo tempo, então a troca
não derruba nenhuma chamada:

1. Gere o par novo (passos 1 a 3).
2. Cadastre a pública nova pela API — `POST .../public-keys`, descrito em
   [Chaves e IPs](/ib/guias/autenticacao/chaves-e-ips#rotacionar-uma-chave).
   Ela entra em carência de 18 horas.
3. Passada a carência, troque a privada no servidor. O `kid` muda junto.
4. Aposente a chave antiga (`DELETE .../public-keys/{kid}`). Remover vale
   na hora.

Se a privada vazou, não espere a rotação: aposente a chave ou peça ao
titular para revogar a credencial no internet banking. As duas coisas valem
imediatamente.

## Próximo passo

Com a credencial ativa, [assine as requisições](/ib/guias/autenticacao/assinatura-de-requisicoes)
— ou vá direto aos [exemplos de código](/ib/guias/autenticacao/exemplos-de-assinatura).