> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciar Api Keys

> Como criar, listar e revogar chaves de API no dashboard da Chargefy

As **Api Keys** são tokens de acesso que permitem integrar a Chargefy com seus sistemas, parceiros ou automações. Cada organização gera as próprias chaves pelo dashboard, controla escopos e ambiente, e pode revogar a qualquer momento.

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

## Requisitos

* Você precisa ser **owner** ou **admin** da organização pra criar/revogar chaves. Membros comuns (`member`) não têm acesso ao menu
* A tela fica em **Settings → Chaves de API** no dashboard

## Criar uma chave

1. Acesse `https://app.chargefy.io/dashboard/<sua-org>/settings/api-keys`
2. Clique em **Nova chave**
3. Preencha:
   * **Nome** — descritivo, ajuda depois a identificar ("Produção", "Integração Stripe", "Teste local")
   * **Ambiente** — `live` (produção) ou `test` (sandbox; transações Zoop isoladas)
   * **Permissões** — `read` pra consultas, `write` pra criar/atualizar. Marque só o que precisar
4. Clique em **Criar chave**
5. **Copie o token agora** — ele aparece uma única vez. Botão **Copiar** copia pro clipboard; aperte também pra abrir no menu contextual

O token tem o formato `ch_live_<43 chars>` ou `ch_test_<43 chars>`. Guarde em:

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

> [!WARNING]
>
> Se perder o token, **não há recuperação**. A plataforma só armazena o hash. Crie uma nova chave e revogue a antiga.

## Listar chaves

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

* Nome e prefixo mascarado (ex: `ch_live_…xyz9`)
* Ambiente (`live` ou `test`)
* Escopos concedidos
* Data de criação e último uso
* Data de expiração (se definida)

Marque **Mostrar revogadas** pra incluir chaves desativadas no histórico — útil pra auditoria.

> [!NOTE]
>
> A coluna "último uso" é atualizada em tempo real. Se uma chave aparece como "nunca usada" mas você tem certeza que a aplicação consumiu, o hash no seu código provavelmente está errado ou o header não chegou no servidor.

## Usar a chave nas requests

### Header recomendado

```bash theme={null}
curl https://api.chargefy.io/v1/sales/ \
  -H "X-Chargefy-Api-Key: ch_live_AbCd1234…"
```

### Bearer compatibility

Pra clients que só aceitam `Authorization: Bearer`:

```bash theme={null}
curl https://api.chargefy.io/v1/sales/ \
  -H "Authorization: Bearer ch_live_AbCd1234…"
```

### SDK oficial

```typescript theme={null}
import { Chargefy } from '@chargefy/sdk'

const chargefy = new Chargefy({
  apiKey: process.env.CHARGEFY_API_KEY!,  // ou CHARGEFY_TEST_KEY
})

const sales = await chargefy.sales.list({ limit: 10 })
```

Exemplos completos por linguagem em [SDKs](https://scaleup-c34c4386.mintlify.site/integrate/sdk/typescript.md).

## Revogar uma chave

Na lista, clique em **Revogar** ao lado da chave alvo. Confirme no diálogo.

Efeitos imediatos:

* Próxima request com aquele token retorna `401 Unauthorized`
* A chave passa pra seção "Revogadas" (visível com o toggle)
* Nome, último uso e metadata ficam preservados pra auditoria

> [!WARNING]
>
> Revogação não pode ser desfeita. Se precisar voltar atrás, crie uma chave nova e atualize a aplicação.

### Quando revogar

* **Obrigatório:** token vazou (commit acidental, laptop roubado, funcionário saiu)
* **Recomendado:** rotação periódica (cada 90-180 dias), especialmente em ambiente `live`
* **Hygiene:** chaves de integração descontinuada, não usadas há muito tempo

### Workflow de rotação (zero downtime)

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

1. **Criar** nova chave com mesmo nome + sufixo (ex: "Produção v2")
2. **Atualizar** a variável de ambiente da aplicação pra usar o novo token
3. **Deploy** e confirmar (olhe "último uso" da chave nova)
4. **Revogar** a chave antiga

## Escopos

Os escopos definem o que a chave pode fazer:

### `read`

Endpoints GET disponíveis:

* `/v1/subscriptions/*`, `/v1/customers/*`
* `/v1/sales/*`, `/v1/transactions/*`
* `/v1/products/*`, `/v1/checkout-links/*`

### `write`

Inclui tudo de `read` + endpoints de mutação:

* `POST /v1/customers/` — criar customer
* `POST /v1/transactions/` — criar transação (boleto/pix/card)
* `POST /v1/subscriptions/` — criar assinatura
* `POST /v1/refunds/` — estornar
* `PATCH` / `DELETE` nos recursos acima

### `admin`

Reservado pra operações críticas (gerenciar api keys via api key, etc). **Não exposto na UI atualmente** — se precisar, abra um ticket.

## Expiração

Ao criar a chave você pode opcionalmente definir uma data de expiração. Após essa data:

* Requests retornam `401 Unauthorized — api key expired`
* A chave aparece na lista com badge "expirada"
* Você pode reativar criando uma nova — não há "renovar"

Útil pra:

* Acessos temporários (pilotos de parceiros)
* Acessos de equipe externa com escopo de tempo
* Forçar rotação disciplinada

## Boas práticas

> [card] Uma chave por integração
>
> Criar chaves separadas por serviço/ambiente facilita revogação cirúrgica e auditoria ("quem usou o quê").

> [card] Monitore last\_used\_at
>
> Chaves não usadas há mais de 30 dias são candidatas a revoke preventivo.

> [card] Mantenha nomes descritivos
>
> "Integração X — Produção — Rotacionada 2026-04" é melhor que "Produção 2".

> [card] Princípio do menor privilégio
>
> Só marque `write` se realmente precisa criar/atualizar. Leitura é suficiente pra dashboards de terceiro.

## Troubleshooting

### "Missing X-Chargefy-Api-Key header"

O header não chegou no servidor. Verifique:

* O nome do header está exato (case-insensitive mas literal: `X-Chargefy-Api-Key`)
* Proxies/middlewares não estão strippando o header
* `Authorization: Bearer ch_...` também funciona como fallback

### "Invalid api key"

O hash não bate. Causas comuns:

* Token copiado com espaço extra no início/fim
* Chave revogada ou soft-deleted
* Prefixo errado (tem que ser `ch_live_` ou `ch_test_`)

### "Api key lacks required scope"

A chave não tem o escopo necessário pra aquele endpoint. Crie uma nova com o escopo apropriado e atualize a aplicação.

### "Api key expired"

Ultrapassou a data de expiração. Crie uma nova.

### `429 Too Many Requests`

Rate limit da plataforma. Implemente retry com backoff exponencial.

## Próximos Passos

> [card] [Autenticação](https://scaleup-c34c4386.mintlify.site/integrate/authentication.md)
>
> Resumo dos métodos de auth

> [card] [SDK TypeScript](https://scaleup-c34c4386.mintlify.site/integrate/sdk/typescript.md)
>
> Usa a chave automaticamente

> [card] [Webhooks](https://scaleup-c34c4386.mintlify.site/integrate/webhooks/endpoints.md)
>
> Configure webhooks assinados pra receber eventos

> [card] [Sandbox](https://scaleup-c34c4386.mintlify.site/integrate/sandbox.md)
>
> Teste com chave `ch_test_` sem custo


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.