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

# Gerenciar API keys

> Crie, liste, revogue e rotacione chaves de API no dashboard da Chargefy — chaves de organização e de plataforma.

Uma **API key** é o token que autentica integrações server-to-server com a Chargefy. Cada chave pertence a uma organização, carrega escopos que limitam o que ela pode fazer e vive em um ambiente (`live` ou `test`). Você gera, lista e revoga chaves pelo dashboard, em **Settings → Chaves de API**.

<Info>
  **Chave de organização ≠ chave de plataforma**

  Uma **chave de organização** atua apenas na própria organização e usa escopos `read` / `write` / `admin`. Uma **chave de plataforma** tem o escopo exclusivo `platform_admin` e age em organizações conectadas ativas, indicadas no header `Organization`. As duas têm o mesmo formato de token e o mesmo ciclo de vida — o que muda é o escopo e o alcance.
</Info>

Este guia cobre o ciclo de vida completo: criar, usar, listar, revogar e rotacionar.

## Requisitos

* Você precisa ser **owner** ou **admin** da organização para criar, listar ou revogar chaves. Membros comuns (`member`) não enxergam o menu nem conseguem operar chaves.
* A tela fica em **Settings → Chaves de API** no dashboard (`https://dashboard.chargefy.io/dashboard/<sua-org>/settings/api-keys`).
* Para criar **chaves de plataforma**, a plataforma precisa estar **ativa** e ter o **setup concluído** (regras de split configuradas). Sem isso, a geração de chave é bloqueada.

## Formato do token

O token segue sempre o mesmo formato: prefixo de ambiente + corpo aleatório.

```
ch_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
└┬─┘ └─┬┘ └────────────────┬────────────────┘
 │     │                   │
 │     │                   └── 43 caracteres aleatórios (base64url)
 │     └── ambiente: live ou test
 └── prefixo Chargefy
```

| Parte    | Valor              | Significado                                                          |
| -------- | ------------------ | -------------------------------------------------------------------- |
| Prefixo  | `ch_`              | Identifica um token da Chargefy.                                     |
| Ambiente | `live_` ou `test_` | `ch_live_` opera com dados reais; `ch_test_` é isolado para sandbox. |
| Corpo    | 43 caracteres      | 32 bytes aleatórios em base64url, sem padding.                       |

<Warning>
  O token aparece **uma única vez**, no momento da criação. A plataforma guarda apenas o hash (SHA-256) — não há como recuperar o texto claro depois. Se perder, **revogue e crie uma nova**.
</Warning>

## Ambientes: `live` vs `test`

Toda chave nasce em um ambiente, escolhido na criação (default `live`):

| Ambiente | Prefixo    | Quando usar                                                    |
| -------- | ---------- | -------------------------------------------------------------- |
| `live`   | `ch_live_` | Produção — cobranças e dados reais.                            |
| `test`   | `ch_test_` | Sandbox — desenvolvimento e testes sem efeito financeiro real. |

O ambiente da chave determina o campo `livemode` das respostas e dos webhooks: chave `live` produz `livemode: true`, chave `test` produz `livemode: false`. Mantenha chaves separadas por ambiente e nunca aponte produção para uma chave `test`.

## Criar uma chave de organização

<Steps>
  <Step title="Abra a tela de chaves">
    Acesse **Settings → Chaves de API** como **owner** ou **admin** e clique em **Nova chave**.
  </Step>

  <Step title="Preencha os campos">
    * **Nome** — descritivo, ajuda a identificar depois (`Produção`, `Integração faturamento`).
    * **Permissões** — marque `read`, `write` ou ambos. O default é `read` + `write`. Marque só o que a integração precisa.
    * **Ambiente** — `live` ou `test`.
    * **Expiração** *(opcional)* — uma data futura em que a chave deixa de funcionar.
  </Step>

  <Step title="Crie e copie o token">
    Clique em **Criar chave** e **copie o token imediatamente** — ele aparece uma única vez. Use o botão **Copiar** para levar ao clipboard.
  </Step>
</Steps>

Guarde o token em:

* Secret manager (AWS Secrets Manager, Google Secret Manager, Doppler, 1Password, Vault).
* Variáveis de ambiente do seu servidor (`CHARGEFY_API_KEY`).
* **Nunca** em código-fonte versionado, em log, ou em frontend/mobile.

## Criar uma chave de plataforma

Plataformas — organizações que orquestram pagamentos para organizações conectadas — usam um tipo de chave próprio, com escopo `platform_admin`. Ela é criada na configuração da plataforma, não na tela de chaves comum.

<Steps>
  <Step title="Conclua o setup da plataforma">
    A plataforma precisa estar **ativa** e ter as **regras de split configuradas**. Enquanto o setup não estiver concluído, a criação de chave fica bloqueada.
  </Step>

  <Step title="Gere a chave">
    Como **owner** ou **admin** da organização dona da plataforma, gere a chave informando um **nome** e o **ambiente** (`live` ou `test`).
  </Step>

  <Step title="Copie o token">
    Mesma regra: o token aparece uma vez só. Guarde em secret manager.
  </Step>
</Steps>

<Note>
  Chave de plataforma sempre nasce com o escopo `platform_admin` — não há seleção de escopo. Para atuar em uma organização conectada, envie o header `Organization` na request (veja [Usar a chave](#usar-a-chave-nas-requests)).
</Note>

## Usar a chave nas requests

A chave pode ser enviada de duas formas, ambas aceitas:

<CodeGroup>
  ```bash Authorization (recomendado) theme={}
  curl https://api.chargefy.io/v1/products \
    -H "Authorization: Bearer {{API_KEY}}"
  ```

  ```bash Header dedicado theme={}
  curl https://api.chargefy.io/v1/products \
    -H "X-Chargefy-Api-Key: {{API_KEY}}"
  ```
</CodeGroup>

Chave de plataforma indica a organização conectada-alvo no header `Organization`:

```bash theme={}
curl https://api.chargefy.io/v1/products \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: id_123"
```

<Tip>
  Para exemplos completos de cada endpoint, consulte a [Referência da API](/api-reference/introduction). O resumo dos métodos de autenticação fica em [Autenticação](/integrate/authentication).
</Tip>

## Escopos

Os escopos definem o que a chave pode fazer. Chaves de organização usam `read` / `write` / `admin`; chaves de plataforma usam `platform_admin`.

| Escopo           | Tipo de chave | Permissão                                                                      |
| ---------------- | ------------- | ------------------------------------------------------------------------------ |
| `read`           | Organização   | Listar e consultar recursos (`GET`).                                           |
| `write`          | Organização   | Tudo de `read` + criar, atualizar e desativar recursos (`POST`, `DELETE`).     |
| `admin`          | Organização   | Tudo de `write` + operações críticas. Reservado; não exposto na UI atualmente. |
| `platform_admin` | Plataforma    | Atuar em organizações conectadas ativas via header `Organization`.             |

<Info>
  Os escopos de organização são **hierárquicos**: `write` inclui `read`, e `admin` inclui ambos. Um endpoint que exige `read` aceita também chaves `write` ou `admin`. Já `platform_admin` é exclusivo: chave de organização não satisfaz endpoint de plataforma, e vice-versa.
</Info>

### O que cada escopo cobre

<AccordionGroup>
  <Accordion title="read — leitura">
    Endpoints `GET`: consultar e listar `customers`, `products`, `prices`, `payment-links`, `payment-intents`, `payment-methods`, `setup-intents`, `charges`, `files`, `organizations`, `onboarding-sessions`.
  </Accordion>

  <Accordion title="write — leitura + mutação">
    Tudo de `read` mais os `POST` e `DELETE` que criam, atualizam ou desativam recursos — por exemplo `POST /v1/customers`, `POST /v1/products`, `POST /v1/payment-links`, além das ações e remoções documentadas em cada recurso.
  </Accordion>

  <Accordion title="admin — operações críticas">
    Inclui tudo de `write`. Reservado para operações sensíveis. **Não exposto no dashboard atualmente** — se precisar, abra um ticket.
  </Accordion>

  <Accordion title="platform_admin — plataforma">
    Exclusivo de chaves de plataforma. Permite operar em organizações conectadas ativas, indicadas no header `Organization`. Não satisfaz endpoints que exigem escopo de organização sem esse roteamento.
  </Accordion>
</AccordionGroup>

<Warning>
  Siga o **princípio do menor privilégio**: crie chaves `read` quando a integração só consulta dados, e `write` apenas onde precisa criar ou modificar.
</Warning>

## Listar chaves

A página principal mostra as chaves da organização com:

* Nome e prefixo mascarado (ex: `ch_live_…Qr2x`, mostrando só os 4 últimos caracteres).
* Escopos concedidos.
* Ambiente (`live` / `test`).
* Data de criação e último uso (`last_used_at`).
* Data de expiração, quando definida.

Marque **Mostrar revogadas** para incluir chaves desativadas no histórico — útil para auditoria. Chaves revogadas preservam nome, último uso, quem revogou e o motivo.

<Info>
  A coluna "último uso" é atualizada a cada request autenticada. Se uma chave aparece como "nunca usada" mas você tem certeza de que a aplicação a consumiu, provavelmente o token está errado ou o header não chegou ao servidor.
</Info>

## Revogar uma chave

Na lista, clique em **Revogar** ao lado da chave alvo e confirme. Opcionalmente registre um **motivo** (`vazou`, `rotação`) para auditoria.

Efeitos imediatos:

* A próxima request com aquele token retorna `401 Unauthorized`.
* A chave passa para a seção "Revogadas" (visível com o toggle).
* Nome, último uso, quem revogou, quando e por quê ficam preservados — a revogação é um soft-delete, não apaga o histórico.

<Warning>
  Revogação **não pode ser desfeita**. Para voltar atrás, crie uma chave nova e atualize a aplicação. Tentar revogar uma chave já revogada retorna `409`.
</Warning>

### Quando revogar

| Situação                                                         | Urgência                  |
| ---------------------------------------------------------------- | ------------------------- |
| Token vazou (commit acidental, laptop roubado, funcionário saiu) | **Obrigatório, imediato** |
| Rotação periódica (a cada 90–180 dias)                           | Recomendado               |
| Chave de integração descontinuada ou parada há muito tempo       | Higiene                   |

### Rotação sem downtime

A plataforma não suporta rotação in-place — siga este fluxo:

<Steps>
  <Step title="Criar">
    Gere uma chave nova com o mesmo nome + sufixo (`Produção v2`) e mesmos escopos/ambiente.
  </Step>

  <Step title="Atualizar">
    Aponte a variável de ambiente da aplicação para o novo token.
  </Step>

  <Step title="Deploy e confirmar">
    Faça o deploy e confira o "último uso" da chave nova subindo.
  </Step>

  <Step title="Revogar">
    Revogue a chave antiga.
  </Step>
</Steps>

## Expiração

Na criação você pode definir uma data de expiração **futura** (ISO 8601). Depois dessa data:

* Requests retornam `401 Unauthorized — api key expired`.
* A chave aparece na lista com badge "expirada".
* Não há "renovar" — crie uma nova chave para seguir.

Útil para acessos temporários (pilotos de parceiros), equipes externas com janela de tempo definida, ou para forçar rotação disciplinada.

## Boas práticas

<CardGroup cols={2}>
  <Card title="Uma chave por integração" icon="check">
    Chaves separadas por serviço facilitam revogação cirúrgica e auditoria de "quem usou o quê".
  </Card>

  <Card title="Separe live de test" icon="layer-group">
    Use `ch_test_` em desenvolvimento e `ch_live_` em produção. Nunca aponte produção para uma chave de teste.
  </Card>

  <Card title="Monitore o último uso" icon="clock">
    Chaves paradas há mais de 30 dias são candidatas a revogação preventiva.
  </Card>

  <Card title="Menor privilégio" icon="lock">
    Só conceda `write` quando a integração realmente precisa criar ou modificar. Leitura basta para dashboards de terceiros.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Unauthorized — missing API key">
    O header não chegou ao servidor. Verifique se a request usa `Authorization: Bearer <token>` ou `X-Chargefy-Api-Key: <token>`, e que proxies/middlewares não estão removendo o header.
  </Accordion>

  <Accordion title="Unauthorized — invalid api key">
    O hash não bate. Causas comuns: token copiado com espaço extra, chave revogada/expirada, ou prefixo incorreto (precisa começar com `ch_`).
  </Accordion>

  <Accordion title="Forbidden — api key lacks required scope">
    A chave não tem o escopo do endpoint. Crie uma nova com o escopo apropriado e atualize a aplicação. Lembre que `platform_admin` não satisfaz endpoints de organização sem o header `Organization`.
  </Accordion>

  <Accordion title="Unauthorized — api key expired">
    A data de expiração passou. Crie uma nova chave.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    Rate limit da plataforma. Implemente retry com backoff exponencial.
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key" href="/integrate/authentication">
    Resumo dos métodos de auth e respostas de erro.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integrate/webhooks/delivery">
    Verifique webhooks assinados.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Consulte os endpoints públicos.
  </Card>
</CardGroup>