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

# Autenticação

> Como autenticar chamadas na API Veepag usando apiKey ou token.

Para proteger sua operação e os dados dos seus clientes, a maior parte dos endpoints públicos da Veepag exige autenticação por header.

Você pode autenticar suas chamadas com `apiKey` ou `token`. Use a opção combinada com o time Veepag durante a configuração da sua integração.

| Header   | Obrigatório                      | Formato        | Uso                                       |
| -------- | -------------------------------- | -------------- | ----------------------------------------- |
| `apiKey` | Sim, se `token` não for enviado  | `keyId.secret` | API key da integração.                    |
| `token`  | Sim, se `apiKey` não for enviado | JWT            | Token com validade confirmada de 14 dias. |

<Warning>
  Use sempre a credencial do ambiente correto. Credenciais de sandbox devem ser usadas com `https://sandbox.api.veepag.com/`; credenciais de produção devem ser usadas com `https://api.veepag.com/`.
</Warning>

## Exemplo com API key

Este é o formato mais comum para integrações servidor-servidor.

```bash theme={null}
curl --request GET 'https://sandbox.api.veepag.com/v1/transaction?page=1&limit=20' \
  --header 'apiKey: keyId.secret'
```

## Exemplo com token

Se sua integração recebeu um `token`, envie-o no header `token`.

```bash theme={null}
curl --request GET 'https://sandbox.api.veepag.com/v1/client?page=1&limit=20' \
  --header 'token: eyJhbGciOi...'
```

## Permissões

Além de autenticar a chamada, a Veepag valida se a credencial tem permissão para acessar o recurso solicitado. Isso ajuda a manter cada integração restrita ao que ela realmente precisa fazer.

| Recurso     | Leitura             | Escrita              |
| ----------- | ------------------- | -------------------- |
| Transações  | `transaction.read`  | `transaction.write`  |
| Clientes    | `client.read`       | `client.write`       |
| Assinaturas | `subscription.read` | `subscription.write` |
| Produtos    | `product.read`      | `product.write`      |
| Cobranças   | `charge.read`       | `charge.write`       |
| Alertas     | `alert.read`        | `alert.write`        |

## Escopo de empresa

O acesso a `companyId` e `companyIds` é validado contra as empresas disponíveis para a credencial.

Se a credencial não tiver acesso à empresa solicitada, a API retorna `403`. Quando isso acontecer, confira se o `companyId` pertence à conta correta e se a credencial tem permissão para aquele recurso.

<Note>
  O CORS aceita headers como `Authorization`, `X-API-Key` e `X-Token`, mas o guard de autenticação da API pública lê `apiKey` e `token`. Para evitar falhas de autenticação, use esses headers.
</Note>

## Exceção: pagamento de cobrança

`POST /v1/charge/pay` usa autenticação por reCAPTCHA (`AuthByCaptchaGuard`) e não segue o mesmo fluxo de `apiKey` ou `token`.

Esse endpoint está mais próximo de um fluxo de checkout/pagamento do que de uma chamada tradicional de API key.