> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caratuva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chaves de API

> Emitir, listar e revogar credenciais servidor-a-servidor.

Chaves de API são as credenciais que integradores B2B apresentam em toda requisição servidor-a-servidor. Cada chave é escopada a uma organização; tenancy é fixada na chave no momento da autenticação e não pode ser sobrescrita por header.

## Formato

```
pk_<modo>_<id>.<segredo>
```

* `<modo>` é `test` ou `live`. Chaves de teste rodam o happy path completo contra uma instância de pagamento sandbox — KYB e KYC do comprador aprovam automaticamente e nenhum dinheiro real se move. Chaves de produção executam contra trilhos reais. Veja [Ambientes](/pt-BR/api-reference/environments).
* `<id>` é a metade pública de lookup — seguro para logar.
* `<segredo>` aparece exatamente uma vez na criação. A Caratuva guarda apenas um hash com salt; o texto plano não é recuperável. Se perder, revogue a chave e crie uma nova.

## Header

```
X-API-Key: pk_live_KEY_ID.KEY_SECRET
```

## Emitir uma chave

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/api-keys \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "content-type: application/json" \
  -d '{
    "name": "ERP integration",
    "mode": "live",
    "scopes": [
      "payment_intents:write",
      "payment_intents:read",
      "webhooks:read"
    ]
  }'
```

`scopes` é opcional. Omitir (ou passar `[]`) emite uma chave irrestrita — útil para a chave de bootstrap mas não recomendado para integrações com escopo restrito. Veja [Escopos](#escopos) abaixo para os valores disponíveis.

Resposta (o campo `secret` é o único lugar onde a chave inteira aparece):

```json theme={null}
{
  "id": "ckxyz...",
  "orgId": "ckorg_...",
  "name": "ERP integration",
  "keyPrefix": "pk_live_KEY_ID",
  "testMode": false,
  "scopes": [
    "payment_intents:write",
    "payment_intents:read",
    "webhooks:read"
  ],
  "lastUsedAt": null,
  "revokedAt": null,
  "createdAt": "2026-05-02T14:00:00.000Z",
  "secret": "pk_live_KEY_ID.KEY_SECRET"
}
```

Guarde o `secret` no cofre imediatamente. Chamadas subsequentes a `GET /v1/api-keys` retornam apenas os metadados — nunca o segredo.

## Listar chaves

```bash theme={null}
curl https://api.caratuva.com/v1/api-keys \
  -H "Authorization: Bearer <dashboard-jwt>"
```

## Revogar uma chave

```bash theme={null}
curl -X DELETE https://api.caratuva.com/v1/api-keys/<id> \
  -H "Authorization: Bearer <dashboard-jwt>"
```

A revogação é irreversível e tem efeito na próxima requisição. Emita a nova chave primeiro, faça deploy dela no integrador, então revogue a antiga para evitar downtime.

## Rotação

Não há endpoint de rotação in-place para chaves de API (diferente de segredos de webhook). O procedimento de rotação é:

1. `POST /v1/api-keys` para criar a nova chave.
2. Deploy da nova chave no integrador.
3. `DELETE /v1/api-keys/<old-id>` para revogar.

O painel mostra `lastUsedAt` para você confirmar que a nova chave está em uso antes de revogar a antiga.

## Escopos

Chaves de API são gateadas por escopo por rota. Uma requisição com chave escopada faltando o escopo necessário retorna `403 InsufficientScope`. Escopos disponíveis:

| Escopo                     | Concede                                                               |
| -------------------------- | --------------------------------------------------------------------- |
| `payment_intents:write`    | `POST /v1/payment-intents`, cancel                                    |
| `payment_intents:read`     | `GET /v1/payment-intents/:id`                                         |
| `invoices:write`           | `POST /v1/invoices`, cancel, invite-buyer                             |
| `invoices:read`            | `GET /v1/invoices`, `GET /v1/invoices/:id`                            |
| `webhooks:write`           | `POST /v1/webhook-subscriptions`, delete, rotate-secret               |
| `webhooks:read`            | `GET /v1/webhook-subscriptions`, deliveries                           |
| `api_keys:write`           | `POST /v1/api-keys`, revoke                                           |
| `connected_accounts:write` | `POST /v1/connected-accounts`, tos, upload-url, submit, payout-config |
| `connected_accounts:read`  | `GET /v1/connected-accounts`, `GET /v1/connected-accounts/:id`        |

Conjunto recomendado de início para uma integração B2B que cria intents e reconcilia via webhooks:

```json theme={null}
[
  "payment_intents:write",
  "payment_intents:read",
  "webhooks:read"
]
```

(Nota: a gestão de inscrições de webhook é melhor feita pelo painel, não pelo runtime do integrador — então `webhooks:write` geralmente é desnecessário.)

### Nota de retrocompatibilidade

Chaves emitidas antes dos escopos existirem têm `scopes = []`, o que a Caratuva trata como **irrestrito** para preservar o comportamento existente delas. Para migrar, emita uma nova chave com escopos explícitos, faça deploy, depois revogue a sem escopo.

## Teste vs. produção

Use chaves `pk_test_*` contra ambientes de staging e CI. Chaves de teste são marcadas no principal autenticado como `testMode: true`. O fluxo inteiro — KYC do comprador, coleta de pagamento, transferência internacional, câmbio e repasse PIX — roda contra uma instância de pagamento sandbox: KYB e KYC do comprador aprovam automaticamente e nenhum dinheiro real se move. Chaves de produção batem em trilhos de produção; nunca use fora de produção. Veja [Ambientes](/pt-BR/api-reference/environments) para o modelo completo de modos.