> ## 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.

# Autenticação

> Como autenticar suas requisições à API da Chargefy

A Chargefy oferece dois caminhos de autenticação, cada um pra um tipo de integração.

## Métodos de Autenticação

| Método | Header | Caso de Uso |
| - | - | - |
| **Api Key** | `X-Chargefy-Api-Key: ch_live_…` | Integrações server-side de parceiros. Token gerado no dashboard da Chargefy, longo-prazo, revogável a qualquer momento. **Recomendado pra uso em produção.** |
| Customer Session Token (CST) | `Authorization: Bearer <token>` | Portal do cliente. Sessão gerada pelo fluxo de login do customer. Não usar pra integração server-side. |

## Api Key

O método principal pra integrações server-side. Cada organização gera os próprios tokens no dashboard da Chargefy, em **Settings → Chaves de API**.

### Formato do token

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

O token aparece **uma vez só**, no momento da criação. A plataforma guarda apenas o hash — não há como recuperar o texto claro depois. Se perder, revogue e crie uma nova.

### Como usar

Envie o token no header `X-Chargefy-Api-Key`:

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

Alternativa compatível com clients que só aceitam `Bearer`:

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

```typescript theme={null}
const response = await fetch('https://api.chargefy.io/v1/sales/', {
  headers: {
    'X-Chargefy-Api-Key': process.env.CHARGEFY_API_KEY!,
  },
});
```

### Ambientes

Quando você cria uma chave, escolhe o ambiente:

| Ambiente | Prefixo | Comportamento |
| - | - | - |
| `live` | `ch_live_…` | Executa transações Zoop reais, aparece em relatórios financeiros |
| `test` | `ch_test_…` | Mesmas rotas, mas isolado pra testes/integração. Não produz cobrança real. |

Mantenha keys `test` no seu ambiente de staging e `live` apenas em produção. Nunca commite em código-fonte.

### Escopos

Cada chave carrega um ou mais escopos que limitam o que ela pode fazer:

| Escopo | Permissão |
| - | - |
| `read` | Listar e consultar recursos (sales, subscriptions, customers, etc) |
| `write` | Criar, atualizar e cancelar recursos (transactions, refunds, subscriptions) |
| `admin` | Reservado pra operações críticas. Não exposto no dashboard atualmente |

Hierarquia: `write` inclui `read`; `admin` inclui ambos. Um endpoint que exige `scope: 'read'` aceita também chaves com `write`.

> [!NOTE]
>
> Siga o **princípio do menor privilégio**: crie chaves com `read` apenas quando a integração só precisa consultar dados. Use `write` só onde realmente precisa criar/modificar.

### Obtendo uma chave

1. Entre no dashboard da Chargefy como **owner** ou **admin** da organização
2. Abra **Settings → Chaves de API**
3. Clique em **Nova chave**
4. Dê um nome descritivo ("Produção", "Integração X"), escolha ambiente e escopos
5. Clique em **Criar chave**
6. **Copie o token imediatamente** — ele aparece uma vez só

Mais detalhes em [Gerenciar api keys](https://scaleup-c34c4386.mintlify.site/integrate/api-keys.md).

### Rotação e revogação

* **Revogação instantânea**: na lista de chaves, clique em **Revogar**. Requests com aquele token passam a retornar `401` em milissegundos
* **Rotação**: não há "rotate key" in-place; o workflow é:
  1. Criar chave nova
  2. Atualizar sua aplicação pra usar a nova
  3. Revogar a antiga
* **last\_used\_at**: a plataforma guarda o último uso. Chaves não utilizadas há muito tempo podem ser revogadas preventivamente

### Respostas de autenticação

Credencial ausente ou inválida:

```json theme={null}
{ "error": "Unauthorized — missing X-Chargefy-Api-Key header" }
```

```json theme={null}
{ "error": "Unauthorized — invalid api key" }
```

```json theme={null}
{ "error": "Unauthorized — api key revoked" }
```

```json theme={null}
{ "error": "Unauthorized — api key expired" }
```

Escopo insuficiente:

```json theme={null}
{ "error": "Forbidden — api key lacks required scope \"write\"" }
```

### Segurança

> [!WARNING]
>
> * **Nunca** exponha `X-Chargefy-Api-Key` em código client-side (browser, mobile). Faça todas as chamadas server-side
> * Armazene em variáveis de ambiente (`CHARGEFY_API_KEY` / `CHARGEFY_TEST_KEY`), nunca em código-fonte versionado
> * Use escopos mínimos necessários
> * Revogue imediatamente qualquer chave comprometida (vazamento em log, commit, laptop roubado)
> * Revogação é instantânea — não há janela de uso de token antigo

## Customer Session Token (CST)

Tokens de sessão do cliente são usados pra autenticar operações no portal do cliente (`/portal`). Não servem pra integração server-side.

### Como funciona

1. O cliente entra no portal via email/link mágico
2. A aplicação troca o login por um token de sessão curto
3. O token é usado nos endpoints do Customer Portal

```typescript theme={null}
// Autenticar cliente
const session = await fetch('https://api.chargefy.io/v1/customer-portal/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'cliente@email.com' }),
});

// Usar token
const { token } = await session.json();

const sales = await fetch('https://api.chargefy.io/v1/customer-portal/sales/', {
  headers: { 'Authorization': `Bearer ${token}` },
});
```

### Endpoints acessíveis via CST

O CST dá acesso exclusivo aos endpoints do [Customer Portal API](https://scaleup-c34c4386.mintlify.site/api-reference/customer-portal/get-customer.md):

* Visualizar perfil do cliente
* Listar e gerenciar assinaturas
* Histórico de vendas
* Acessar chaves de licença
* Download de arquivos/benefícios

## Próximos Passos

> [card] [Gerenciar Api Keys](https://scaleup-c34c4386.mintlify.site/integrate/api-keys.md)
>
> Criar, listar, revogar chaves no dashboard

> [card] [SDK TypeScript](https://scaleup-c34c4386.mintlify.site/integrate/sdk/typescript.md)
>
> Configura autenticação automaticamente

> [card] [Ambiente Sandbox](https://scaleup-c34c4386.mintlify.site/integrate/sandbox.md)
>
> Teste integrações em ambiente isolado

> [card] [Webhooks](https://scaleup-c34c4386.mintlify.site/integrate/webhooks/endpoints.md)
>
> Receba eventos assinados em tempo real


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