# PIX Keys

Lists the PIX keys registered to the account associated with the API Key.

## Endpoint

```
GET /api/external/pix/keys
```

## Headers

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| `Authorization` | String | Yes | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | No | Set to `camelCase` to receive response fields in camelCase (default is snake_case) |

## Example

```bash
curl -X GET https://api.monetarie.com/api/external/pix/keys \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

## Success Response (200)

```json
{
  "worked": true,
  "keys": [
    {
      "key": "12345678901",
      "key_type": "cpf",
      "status": "active",
      "created_at": "2026-02-05T12:00:00Z"
    },
    {
      "key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "key_type": "evp",
      "status": "active",
      "created_at": "2026-02-10T14:30:00Z"
    },
    {
      "key": "contato@empresa.com.br",
      "key_type": "email",
      "status": "active",
      "created_at": "2026-02-15T09:00:00Z"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `worked` | Boolean | `true` indicates operation success |
| `keys` | Array | List of PIX keys for the account, ordered by `inserted_at ASC` (oldest to most recent). **Note:** when a PIX IN charge (`POST /pix/cash-in`) is generated without the `pix_key` parameter, the backend internally uses the most **recent** `active` key of the account (`DESC`) - different order from this endpoint. |
| `keys[].key` | String | PIX key value |
| `keys[].key_type` | String | Key type in lowercase (see table below) |
| `keys[].status` | String | Current key status (see table below) |
| `keys[].created_at` | String | Registration date (ISO 8601 in UTC) |

::: info No pagination
This endpoint **returns all account keys in a single response** (individual accounts allow up to 5 keys, business accounts up to 20). There are no `limit`, `offset`, `page`, or `per_page` parameters -- sending these parameters is silently ignored.
:::

## Key Types

| Type | Format | Example |
|------|--------|---------|
| `cpf` | 11 digits | `12345678901` |
| `cnpj` | 14 digits | `12345678000190` |
| `email` | Valid email | `contato@empresa.com.br` |
| `phone` | area code + number (11 digits) | `11999998888` |
| `evp` | UUID v4 (random key) | `a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d` |

## Key Status

The DB schema accepts **only two values** for `status`:

| Status | Description |
|--------|-------------|
| `active` | Key is active and operational -- can receive PIX and be used as `pix_key` in `POST /pix/cash-in` |
| `pending` | Registration being processed in DICT (key creation flow started but not yet confirmed by BACEN) |

::: info Keys displayed
The endpoint returns **all** keys linked to the account (regardless of status). Filter by `status === "active"` in the client if you only want operational keys.
:::

::: info Portability and claims
**Portability is not a key status**. Portability (bringing a key from another institution) and claim (disputing ownership) are separate workflows, available only in the **merchant portal** or via the **admin panel** -- not exposed by the external API.
:::

## Error Response (401)

```json
{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}
```

::: info External API is read-only
This endpoint **only lists** existing keys. Registration, portability, claims, and deletion of PIX keys are done exclusively via the **merchant portal** (merchant.monetarie.com) or **admin panel** -- there are no external endpoints for these operations.

Information on limits (managed by the backend, not exposed by the API): individual accounts allow up to 5 keys, business accounts up to 20, with 1 CPF/CNPJ key per account.
:::