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

# Autenticação

> Bearer Token, permissões e escopo por loja.

A API da AgitaPay usa **Bearer Token** (HTTP Authorization).

```http theme={null}
Authorization: Bearer agp_li...xxxx
```

## Como obter uma chave

1. Entre no painel AgitaPay.
2. Acesse **Integrações** e crie uma nova chave.
3. Escolha as permissões da loja e copie a chave na hora — ela aparece uma única vez; depois disso o painel guarda apenas o hash SHA-256.

## Regras de segurança

* Nunca envie token por query string.
* Nunca exponha chaves no frontend ou em logs.
* Token revogado, ausente ou inválido responde `401`.
* Conta sem KYC aprovado responde `403 account_not_approved`.
* Cada token pertence a uma loja; listagens e saldo ficam escopados nessa loja.

## Permissões

| Permissão             | Uso                              |
| --------------------- | -------------------------------- |
| `pix:read`            | Listar e consultar cobranças PIX |
| `pix:write`           | Criar e cancelar cobranças PIX   |
| `payment-links:read`  | Listar e consultar links         |
| `payment-links:write` | Criar links                      |
| `wallet:read`         | Consultar saldo                  |
| `withdrawals:read`    | Listar e consultar saques        |
| `withdrawals:write`   | Solicitar saques                 |

## Allowlist de IP

Opcional e por token. Em branco significa qualquer IP. Quando configurada, requisição de IP fora da lista responde `403 ip_not_allowed`.

## Erros de autenticação

| Código                     | HTTP |
| -------------------------- | ---- |
| `missing_api_token`        | 401  |
| `invalid_api_token`        | 401  |
| `account_not_approved`     | 403  |
| `ip_not_allowed`           | 403  |
| `insufficient_permissions` | 403  |