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

# The API for your account

> **Beta**
>
> The Internet banking API is in **beta**, available only to users invited by
> the bank. Contracts, scopes and behaviour may still change without the
> deprecation cycle of the production BaaS API. If unsure, talk to the bank or
> CorpX support before going to production.

The bank where you hold an account offers **internet banking**. From there,
the account holder can issue a credential so **your system** — ERP, site,
billing app — can talk to the account without using the UI.

This documentation is for whoever received that credential. You are not
becoming a bank and you do not operate other people's accounts: the
credential reaches **one** account, the one the holder authorised.

## Who is who

| Role         | What they do                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------------- |
| **You**      | Keep the private key, call the API, receive webhooks for the account                           |
| **The bank** | Issues and revokes the credential in internet banking; the holder sets locks and PIN in the UI |
| **CorpX**    | Runs `https://client.api.corpx.com` and this API contract                                      |

Credential, IP, public-key and outgoing-lock problems are solved **in the
bank's internet banking**. The API only accepts or refuses what is already
configured.

## What is different from a BaaS integrator

CorpX integrators use `https://tenant.api.corpx.com` and a token. Your
credential is different: the token alone is not enough. Every `/v1/**` call
goes to `https://client.api.corpx.com` and carries a JWS made with the
private key that stayed on **your** server.

The reason is simple. The OAuth token is a bearer — whoever copies it from
a log or a proxy can use it until it expires. The private key never leaves
your server, so a leaked token without it cannot move money.

## What you received

At issuance the internet banking shows (once) and you store:

| Item                          | What it is for                                                                                              |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `clientId` and `clientSecret` | Request the token at `https://auth.api.corpx.com/oauth2/token`                                              |
| `X-Tenant-Id`                 | The identifier the bank showed. Sent on every call — account context, not a value you invent                |
| `accountId`                   | The account the credential reaches. Goes in the path (`/v1/accounts/{accountId}/…`) and on the webhook      |
| Key pair                      | The **private** key stays on your server. The public key is already registered; `kid` says which key signed |
| IP allowlist                  | Which addresses the API accepts calls from. A request from another IP is refused at the edge                |

The credential only accepts calls after **18 hours** (`activeFrom`). Until
then the response is `403 credential_not_yet_active`. Revoking in the bank
UI takes effect immediately. The grace period exists so a human can see an
alert if someone issued a credential the holder did not want.

## Short glossary

| Term              | Meaning                                                                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId`       | Account id in the API (UUID). One credential, one account                                                                                |
| `X-Tenant-Id`     | Slug the bank showed. Without it the API does not know which context you mean                                                            |
| `kid`             | Public-key id, derived from its SHA-256. Check offline that you registered the right key                                                 |
| `activeFrom`      | Instant from which the credential (or a new key / IP) becomes usable                                                                     |
| `Idempotency-Key` | Identity of the HTTP attempt on POST/PUT/PATCH that move money. Repeating the same key returns the original result, not a second payment |
| `identifier`      | Your reconciliation key in the **body**. Shows up on the statement and webhook. Not the same as `Idempotency-Key`                        |

## Next step

Follow the [Quick start](/ib/guias/comece-aqui/primeiros-passos): token, signature self-test
and the first balance. If an agent or LLM will integrate for you, ask it to
read [For agents](/ib/guias/referencia/para-agentes) and
[openapi.yaml](https://docs.api.corpx.com/openapi.yaml) filtered by
`x-audience` containing `ib`.