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.

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.

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

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

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"

{
  "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": [...]}):

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.

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.

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.