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

# Autenticação

Duas camadas, sempre juntas: o **token** prova que a credencial é sua; a
**assinatura** prova que o request saiu do servidor que tem a chave privada.
Uma sem a outra não move dinheiro.

O par de chaves é gerado por você antes da emissão da credencial: a pública
vai para a tela do internet banking, a privada fica no seu servidor. Passo a
passo em [Gerar o par de chaves](/ib/guias/autenticacao/par-de-chaves); código
completo (token + assinatura + chamadas) em
[Exemplos de código](/ib/guias/autenticacao/exemplos-de-assinatura).

## Token

O endereço é o `token_url` que a tela mostrou na emissão, junto com
`client_id` e `client_secret`.

```bash
curl -X POST "https://auth.api.corpx.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"
```

```json
{
  "access_token": "eyJraWQiOiJ…",
  "expires_in": 300,
  "token_type": "Bearer"
}
```

O mesmo `access_token` vale em **todas** as chamadas até expirar. Guarde-o e
só peça outro quando faltar cerca de 60 segundos, ou quando a API recusar o
token. Leia o `expires_in` da resposta — não fixe 300 no cliente.

`scope` é opcional. Omitir devolve um token com todos os escopos da
credencial. Enviar um subconjunto (separado por espaço) restringe aquele
token.

## Headers em toda chamada à API

Host: `https://client.api.corpx.com`.

| Header                | Quando                            | Valor                                                                         |
| --------------------- | --------------------------------- | ----------------------------------------------------------------------------- |
| `Authorization`       | Sempre                            | `Bearer {access_token}`                                                       |
| `X-Tenant-Id`         | Sempre                            | O identificador que o banco mostrou                                           |
| `X-Request-Timestamp` | Sempre                            | Unix em segundos; tolerância de 300s                                          |
| `X-Content-SHA256`    | Sempre                            | SHA-256 do corpo, hex minúsculo                                               |
| `X-Request-Signature` | Sempre                            | JWS detached — [Assinatura](/ib/guias/autenticacao/assinatura-de-requisicoes) |
| `Idempotency-Key`     | POST/PUT/PATCH que criam ou movem | UUID da **tentativa**. Repetir devolve o original                             |

Como montar os três headers de assinatura está no [guia de assinatura](/ib/guias/autenticacao/assinatura-de-requisicoes).
`GET /v1/me` também exige esses headers (é `/v1/**` no host assinado), mas
não exige `X-Tenant-Id`.

## Conferir o token: `GET /v1/me`

```bash
curl -X GET "https://client.api.corpx.com/v1/me" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Request-Signature: $SIG"
```

A resposta traz `clientId`, `scopes` e `tenantRoles[]` com os contextos em
que o token vale. Para uma credencial de internet banking, `sub` e `clientId`
são o mesmo valor.

## O que esta credencial alcança

Ela foi emitida para **uma** conta. Chamadas a outra conta respondem `403
forbidden`.

| Pode                                                      | Fica com o banco / titular                  |
| --------------------------------------------------------- | ------------------------------------------- |
| Consultar saldo, extrato, dados bancários                 | Emitir outra credencial                     |
| Enviar e receber PIX, TED, boleto, transferência interna  | Cadastrar ou resetar PIN de operador        |
| Criar webhook **desta** conta (`accountId` obrigatório)   | Assinar webhook de todas as contas do banco |
| Rotacionar as **suas** chaves e a **sua** allowlist de IP | Abrir conta, backoffice, políticas do banco |
| Ler as travas em vigor                                    | Alterar travas do titular (`PUT` nas locks) |

PIN e travas de horário / IP de origem são da **tela** do internet banking.
Nas rotas de pagamento você **não** envia `X-Transaction-Pin` nem
`X-Acting-Document`: a posse já está na chave privada e no IP da credencial.

## Carência de 18 horas

A emissão devolve `activeFrom` 18h à frente. Até lá: `403
credential_not_yet_active`. Incluir uma chave pública ou um IP novos na
credencial usa a mesma carência; **remover** chave ou IP vale na hora. Detalhe
em [Chaves e IPs](/ib/guias/autenticacao/chaves-e-ips).

Para encerrar antes das 18h a carência da credencial ou de um IP novo na
allowlist dela, abra um ticket com o internet banking. Quem antecipa é a
CorpX, com o ticket e a aprovação de um administrador diferente de quem
pediu. Nem a credencial nem o master que a emitiu conseguem antecipá-la pela
API.