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

# Autenticação e escopos

> Header x-api-key, escopos da chave e formato das respostas.

## Autenticação

Todos os endpoints utilizam autenticação via **API Key** enviada no header `x-api-key`.

Para maior segurança, você pode configurar **domínios e IPs permitidos** na página de Integração, restringindo de onde suas requisições podem ser feitas.

## Escopos da API Key

Ao criar uma API Key, você pode restringi-la a funcionalidades específicas (escopos). Por exemplo, uma chave usada apenas para receber pagamentos pode ter acesso somente a `PIX_IN` e `CHECKOUT`.

| Escopo | Acesso liberado |
| - | - |
| `PIX_IN` | Cobranças PIX (criar, consultar, efetivar homologação) |
| `PIX_OUT` | Saques PIX (criar, consultar) |
| `BOLETO` | Cobranças por boleto (emitir, consultar, cancelar, segunda via, efetivar homologação) |
| `CHECKOUT` | Links de pagamento / checkout (criar, consultar) |
| `WALLET` | Consulta de saldo da carteira |
| `PRODUCTS` | Catálogo de produtos (criar, listar, consultar, atualizar) |
| `WEBHOOKS` | Endpoints de webhook (criar, listar, atualizar, remover, rotacionar a credencial), entregas e reenvio |

> Se nenhum escopo for selecionado, a chave tem **acesso total** a todas as funcionalidades. Chaves criadas antes desta funcionalidade continuam com acesso total (retrocompatível).

> Os escopos são por funcionalidade, não por leitura ou escrita: quem consulta saques (`PIX_OUT`) também pode criá-los. Só `WALLET` é apenas leitura. Para uma integração ou um agente de IA que não deve sacar, não inclua `PIX_OUT`.

Uma requisição feita com uma chave que não possui o escopo necessário retorna **HTTP 403**.

***

## Formato das Respostas

Todas as respostas seguem um formato padrão.

**Sucesso:**

```json theme={null}
{
  "message": "Mensagem descritiva",
  "response": { ... }
}
```

**Erro:**

```json theme={null}
{
  "response": null,
  "errors": ["Descrição do erro"]
}
```


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