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

# Chaves e IPs

A credencial tem um conjunto de chaves públicas e uma allowlist de IPs. Os
dois seguem a mesma assimetria: **ampliar acesso espera 18 horas; reduzir
vale na hora**. A carência existe para um alerta chegar a um humano se
alguém tomou a conta e tentou cadastrar a própria chave ou o próprio IP.

Host: `https://client.api.corpx.com`. Toda chamada leva os headers de
[assinatura](/ib/guias/autenticacao/assinatura-de-requisicoes).

## Rotacionar uma chave

Cada credencial aceita mais de uma chave pública ativa, então a troca não
tem janela de 401:

1. `POST /v1/backoffice/tenants/{tenantId}/credentials/{clientId}/public-keys`
   com a chave nova. A resposta vem `status: pending` e `activeFrom` **18
   horas** à frente.
2. Passadas as 18h, o seu servidor passa a assinar com o `kid` novo.
3. `DELETE .../public-keys/{kid}` aposenta a antiga — **imediato**.

A API recusa aposentar a **última** chave utilizável (`409 last_public_key`):
isso deixaria a credencial inutilizável, sem caminho de volta.

```javascript
// corpo do POST
{ "publicKeyPem": process.env.NEW_PUBLIC_KEY_PEM }
```

`publicKeyPem` é um bloco `-----BEGIN PUBLIC KEY-----` (SPKI) de EC P-256
ou RSA ≥ 2048. Uma PEM de chave **privada** é recusada com `422
invalid_public_key`.

```bash
curl -X GET "https://client.api.corpx.com/v1/backoffice/tenants/$TENANT_ID/credentials/$CLIENT_ID/public-keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Request-Signature: $SIG"
```

## Allowlist de IP

Toda credencial declara de quais IPs ela pode chamar — entre 1 e 20 CIDRs,
obrigatório na emissão. Pedido de fora da lista é recusado na borda, antes
do token (`403 ip_not_allowed`).

```bash
curl "https://client.api.corpx.com/v1/backoffice/tenants/$TENANT_ID/credentials/$CLIENT_ID/ip-allowlist" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Request-Signature: $SIG"
```

```json
{
  "clientId": "abc123...",
  "ips": ["200.10.20.30/32"],
  "pendingIps": ["200.10.20.30/32", "200.10.20.31/32"],
  "pendingUntil": "2026-09-20T06:00:00Z"
}
```

O `PUT` recebe o conjunto **inteiro** (`{"ips": [...]}`):

| Mudança         | Quando vale               |
| --------------- | ------------------------- |
| Remover um IP   | Imediato                  |
| Adicionar um IP | **+18h** (`pendingUntil`) |

`ips` é o que vale agora; `pendingIps` é o conjunto que entra quando a
carência vencer. Se **todas** as entradas do `PUT` forem novas, a lista
antiga continua valendo no intervalo — a intenção é trocar de IP, não
ficar 18 horas sem acesso.

| Regra                                              | Motivo                                                          |
| -------------------------------------------------- | --------------------------------------------------------------- |
| 1 a 20 entradas, obrigatórias                      | Uma credencial sem origem conhecida é só um token a mais        |
| `0.0.0.0/0` recusado (`422 ip_allowlist_required`) | “Qualquer IP” é o mesmo que não declarar                        |
| Prefixo mais largo que `/24` recusado              | `/16` são 65 mil endereços; a lista deixaria de significar algo |

Se o IP de saída do seu servidor mudou (NAT, novo provedor), cadastre o
CIDR novo, espere as 18h e só então troque o roteamento. Enquanto isso a
lista antiga continua valendo.

Se não der para esperar, abra um ticket com o internet banking. A CorpX pode
liberar na hora os IPs em carência, com o ticket e a aprovação de um
administrador diferente de quem pediu; a partir daí `pendingIps` some e os
IPs entram em `ips`. A credencial e o master não antecipam pela API.

## O que o titular vê

O internet banking do banco mostra as chaves e os IPs da credencial. Revogar
a credencial inteira vale na hora e invalida token, chaves e allowlist.