> This page is for BaaS.

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

# Account Security

Three controls the **account holder** configures and the API then enforces on every attempt to move money out: cashout locks, transaction PIN and visibility of who else has access to the account.

They exist for the scenario where the integrator's credential and token are correct — and it is the account holder's session that was taken over. Nothing here is opt-out per request: what the holder configured applies even to the credential that configured it.

> **Nothing changes if you do not use it**
>
> Every account starts with no lock and no PIN, and behaves exactly as it does today. The controls only apply once configured.

## Cashout locks

`account security locks` are three independent limits:

| Field              | Effect                                                                        |
| ------------------ | ----------------------------------------------------------------------------- |
| `cashoutBlocked`   | `true` rejects **every** outgoing payment from the account                    |
| `cashoutHours`     | Only allows outgoing payments inside the window (`HH:MM`, 24h, with timezone) |
| `cashoutSourceIps` | Only allows outgoing payments from declared IPs/CIDRs                         |

In P2P Crypto, an account that advertises **buying** has the order amount held from its own balance. So `cashoutBlocked` pauses its active buy ads, and outside `cashoutHours` they leave the book until the window opens. See [Ads](/baas/guias/p2p/anuncios).

### Read

```bash
curl "https://tenant.api.corpx.com/v1/accounts/acc-123/security/locks" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany"
```

```json
{
  "accountId": "acc-123",
  "current": {
    "cashoutBlocked": false,
    "cashoutHours": { "start": "08:00", "end": "18:00", "timezone": "America/Sao_Paulo" },
    "cashoutSourceIps": ["200.10.20.30/32"]
  },
  "updatedAt": "2026-09-19T12:00:00Z"
}
```

### Write

`PUT` takes the **whole** desired document (scope `security_locks.manage`):

```bash
curl -X PUT "https://tenant.api.corpx.com/v1/accounts/acc-123/security/locks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "X-Acting-Document: 12345678909" \
  -H "X-Acting-Ip: 200.10.20.30" \
  -H "Content-Type: application/json" \
  -d '{
    "cashoutBlocked": false,
    "cashoutHours": { "start": "08:00", "end": "18:00", "timezone": "America/Sao_Paulo" },
    "cashoutSourceIps": ["200.10.20.30/32"]
  }'
```

### Tightening applies now; loosening waits 6 hours

This is the part that changes your flow, so it is worth reading closely: **the decision is made field by field**.

| Change                                       | When it applies |
| -------------------------------------------- | --------------- |
| Turning `cashoutBlocked` on                  | Immediately     |
| Turning `cashoutBlocked` off                 | **+6h**         |
| Narrowing `cashoutHours`, or adding a window | Immediately     |
| Widening or removing `cashoutHours`          | **+6h**         |
| Removing an IP from `cashoutSourceIps`       | Immediately     |
| Adding an IP, or removing the whole list     | **+6h**         |

Someone who turns the block on and widens the window in the same call gets the block **now** and the window **later**. The response says exactly that:

```json
{
  "accountId": "acc-123",
  "current": { "cashoutBlocked": true, "cashoutHours": { "start": "08:00", "end": "18:00" } },
  "pending": { "cashoutBlocked": true, "cashoutHours": { "start": "00:00", "end": "23:59" } },
  "pendingEffectiveAt": "2026-09-19T18:00:00Z",
  "pendingReason": "relaxing_security_requires_grace"
}
```

The asymmetry is the whole design: whoever took over the account wants to **turn off** the block, widen the window, add their own IP — never to tighten. A symmetric grace period would protect the attacker and punish the holder who is reacting to fraud in progress.

### Cancelling or bringing forward the loosening

```bash
# Cancel: discards the pending change, current keeps applying. Immediate.
curl -X DELETE ".../v1/accounts/acc-123/security/locks/pending" ...

# Bring forward: promotes the pending change now. REQUIRES the operator's PIN.
curl -X POST ".../v1/accounts/acc-123/security/locks/pending/approve" \
  -H "X-Acting-Document: 12345678909" \
  -H "X-Transaction-Pin: 918273" ...
```

Bringing it forward is the only path that shortens the grace period, which is why it costs the one thing whoever hijacked the session does not have: the PIN. Without this endpoint, the legitimate holder who wants their own cashout back would have to wait 6h with no alternative.

### `X-Acting-Ip`

When the call comes from a server of yours on the account holder's behalf (the internet banking case), the connection IP is **your** server's, not the end user's. `cashoutSourceIps` would be useless. Pass the user's real IP in `X-Acting-Ip` — that is the one the lock evaluates.

The header is only accepted from integrator credentials. A delegated credential is used directly by its owner, so the connection IP is already the right one and `X-Acting-Ip` is ignored.

### End-user context

An integrator credential may also send the end user's context. Every header is optional, feeds risk analysis, and **never blocks** the payment: an invalid or oversized value is dropped and the call continues.

| Header                | What it is                                                    | Limit          |
| --------------------- | ------------------------------------------------------------- | -------------- |
| `X-Acting-User-Agent` | User-agent of the user's browser or app                       | 512 characters |
| `X-Acting-Device-Id`  | Device identifier from your system                            | 128 characters |
| `X-Acting-Session-Id` | The user's session in your system                             | 128 characters |
| `X-Acting-Geo`        | `latitude,longitude` in decimal degrees (`-22.9068,-43.1729`) | valid range    |

A delegated credential ignores these headers: the caller is the owner, and the connection IP is already theirs.

### Errors

| Code                            | HTTP | When                                                  |
| ------------------------------- | ---- | ----------------------------------------------------- |
| `cashout_locked`                | 423  | `cashoutBlocked: true`                                |
| `cashout_outside_hours`         | 403  | Outside `cashoutHours`. The message states the window |
| `cashout_source_ip_not_allowed` | 403  | Source IP outside `cashoutSourceIps`                  |
| `invalid_cashout_hours`         | 422  | Invalid `HH:MM`, `start == end`, or unknown timezone  |
| `no_pending_change`             | 404  | `DELETE`/`approve` with no scheduled loosening        |

## Transaction PIN

The PIN belongs to the **person** (CPF in `X-Acting-Document`) inside the tenant, not to the account. Two accounts of the same CPF share the PIN and the failure counter. The new family is `/v1/people/pin` (the CPF is a header, not a path segment). The `/v1/accounts/{accountId}/security/pin` routes keep working, with the same JSON, and write that same PIN.

It is only required when the caller's credential is marked for it — in practice, the internet banking credential, where a single credential serves many account holders and the token alone cannot tell who is on the other side of the screen.

### Register and change

```bash
curl -X PUT "https://tenant.api.corpx.com/v1/accounts/acc-123/security/pin" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{ "actingDocument": "12345678909", "pin": "918273" }'
```

```json
{ "accountId": "acc-123", "actingDocument": "123.***.***-09", "status": "created" }
```

Changing an existing PIN requires the current one in the same body (`currentPin`). Without that, whoever hijacked the session would simply change the PIN and the PIN would stop protecting anything.

The scope is `pin.manage`. The PIN never appears in a log or a response — it is stored as an argon2id hash and the clear value is discarded.

When reset on the CorpX page is enabled, a `PUT` **without** `currentPin` for a PIN that already exists returns **403** `pin_change_disabled`. Sending the correct `currentPin` still replaces the PIN while the page is on. The first enrollment does not send `currentPin`.

### PIN rules

| Rule        | Value                                                                                                                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Length      | 6 to 12 digits                                                                                                                                                                                     |
| Digits only | Yes                                                                                                                                                                                                |
| Rejected    | All digits equal (`111111`), sequences including wrap-around (`123456`, `654321`, `890123`), short-period patterns (`121212`, `123123`) and a PIN contained in the holder's birth date or document |

A rejected PIN returns **422** `weak_pin` with the reason named.

### Use

On cashout routes (PIX out, TED, boleto, internal transfer), when the credential requires a PIN:

```bash
curl -X POST ".../v1/accounts/acc-123/pix/payments" \
  -H "X-Acting-Document: 12345678909" \
  -H "X-Transaction-Pin: 918273" ...
```

Missing either one returns **428** `pin_required`.

### Lockout

| Wrong attempts | Effect                                                                               |
| -------------- | ------------------------------------------------------------------------------------ |
| 3              | **15 minute** lock (**429** `pin_temporarily_locked`, with the `Retry-After` header) |
| 6              | Locked until **reset** (**423** `pin_locked`)                                        |

A correct PIN resets the counter. `DELETE` does not remove the row: it hard-locks the person's PIN (`423 pin_locked` on cashout) and they stay enrolled, so the reset request below still works. The facial page also clears the lock.

```bash
curl -X DELETE "https://tenant.api.corpx.com/v1/people/pin" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany" \
  -H "X-Acting-Document: 12345678909"
```

The alias `DELETE /v1/accounts/{accountId}/security/pin/{document}` applies the same lock. With the page turned off, a `PUT` without `currentPin` after that `DELETE` re-enrolls — that is the reset internet banking already does.

### Reset on the CorpX page

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/acc-123/security/pin/reset-request" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{ "actingDocument": "52998224725", "displayMessage": "Confirm your face to choose a new PIN." }'
```

```json
{
  "resetId": "pinrst_8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
  "resetUrl": "https://tenant.api.corpx.com/v1/security/pin-reset#…",
  "expiresAt": "2026-09-27T18:00:00Z"
}
```

The operator opens `resetUrl`, completes the facial check and, if it is approved, chooses the new PIN on that same page. The integrator never sees or chooses the value — this request body does not accept `pin`. `displayMessage` is optional plain text and is shown on the page as sent.

The page uses the tenant's brand: the name, logo and colors configured for it, or the tenant's registered name when no brand is set. CorpX appears only in the footer. The field accepts exactly 6 digits, the length the internet banking PIN keypad enters; `PUT` still accepts 6 to 12.

An existing PIN is required, including a PIN invalidated by `DELETE`. With none, the response is **409** `pin_reset_not_enrolled` and the first enrollment stays on `PUT`. When the page is not enabled for the tenant, the response is **403** `feature_disabled`. The link lasts 30 minutes. The fifth request for the same person in the same hour returns **429** `pin_reset_rate_limited` — the quota is per person, summed across accounts and across the alias. A new request expires earlier open links. The same request exists at `POST /v1/people/pin/reset-request`, with the CPF in `X-Acting-Document`.

### Verify before building the payment

```bash
curl -X POST ".../v1/accounts/acc-123/security/pin/verify" \
  -H "Content-Type: application/json" \
  -d '{ "actingDocument": "12345678909", "pin": "918273" }'
```

This exists so the UI can confirm the PIN **before** the payment form. Without it, the user would only find out the PIN was wrong at the end of the flow — and each mistake would burn one of the 3 attempts. A wrong attempt here counts the same: the endpoint is not a free oracle.

### Operator status

```bash
curl ".../v1/accounts/acc-123/security/pin/status" ...
```

```json
{
  "accountId": "acc-123",
  "items": [
    { "actingDocument": "123.***.***-09", "failedAttempts": 0, "locked": false,
      "setAt": "2026-09-19T12:00:00Z", "updatedAt": "2026-09-19T12:00:00Z" },
    { "actingDocument": "987.***.***-21", "failedAttempts": 6, "locked": true,
      "lockedUntil": null, "requiresReset": true,
      "setAt": "2026-09-01T10:00:00Z", "updatedAt": "2026-09-19T14:22:00Z" }
  ],
  "policy": { "minLength": 6, "maxLength": 12, "softLockAfter": 3,
              "softLockMinutes": 15, "hardLockAfter": 6,
              "digitsOnly": true, "rejectsSequential": true }
}
```

Documents come back masked. `lockedUntil: null` with `requiresReset: true` is the hard lock — the way out is resetting, not waiting.

### Errors

| Code                     | HTTP | When                                                            |
| ------------------------ | ---- | --------------------------------------------------------------- |
| `pin_required`           | 428  | Cashout route without `X-Acting-Document` / `X-Transaction-Pin` |
| `pin_invalid`            | 403  | Wrong PIN. The attempt was counted                              |
| `pin_not_set`            | 403  | That person has no PIN in this tenant                           |
| `pin_temporarily_locked` | 429  | 3 mistakes. Wait out the 15 minutes                             |
| `pin_locked`             | 423  | 6 mistakes, or a PIN invalidated by `DELETE`                    |
| `weak_pin`               | 422  | PIN outside the policy                                          |
| `pin_not_found`          | 404  | `DELETE` for a person with no PIN                               |
| `pin_change_disabled`    | 403  | Replacement without `currentPin` while hosted reset is on       |
| `pin_reset_not_enrolled` | 409  | Reset requested for a person with no PIN                        |
| `pin_reset_rate_limited` | 429  | More than five requests for the same person in the last hour    |

## Shared access

The same bank account can be reached by more than one tenant — the account holder hired two systems, or migrated from one to another and the old one still has access. The holder is entitled to see that:

```bash
curl ".../v1/accounts/acc-123/shared-access" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany"
```

```json
{
  "accountId": "acc-123",
  "items": [
    { "tenantId": "tenant-yourcompany", "displayName": "Your Company",
      "status": "active", "since": "2026-01-15T10:00:00Z", "isCurrent": true },
    { "tenantId": "tenant-other", "displayName": "Other Integrator",
      "status": "suspended", "since": "2025-08-02T09:30:00Z", "isCurrent": false }
  ]
}
```

Public metadata only: display name, state and since when. No credentials, volume, balance or configuration of the other tenants. `status` is the state of that tenant's access to the account, not of the tenant itself — a `suspended` row shows up precisely so the holder can confirm a revocation took effect.

Read scope. Revoking access is a backoffice operation, not this route.

## See also

* [Security recommendations](/baas/guias/autenticacao/recomendacoes-de-seguranca) — what we ask of integrators: user context, IP allowlist, credentials and webhooks
* [Cashout](/baas/guias/pagar/pix-out) — the outgoing routes where locks and PIN apply
* [Request Signing](/ib/guias/autenticacao/assinatura-de-requisicoes) — the other half of the design: one credential per account
* [Errors](/baas/guias/referencia/erros) — full catalog