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

# Chaves de API

> Criar, rotacionar e proteger gp_live_ — header X-API-Key, trilho e IP allowlist

Chaves de API (`gp_live_...`) autenticam integrações **server-to-server**. Não usam sessão de usuário do dashboard.

Tutorial visual: [Criar chave de API](/tutorials/api-key). Fluxo completo até o primeiro PIX: [Primeira integração](/pages/guides/primeira-integracao).

## Criar a chave

**Integrações → Chaves de API** em [app.goatpay.com.br](https://app.goatpay.com.br/dashboard/integrations/api).

| Campo        | Descrição                                            |
| ------------ | ---------------------------------------------------- |
| Descrição    | Identifique o sistema (ex. `ERP Produção`)           |
| Preset       | `read`, `write` ou `full` — ajuste permissões depois |
| Trilho       | `PADRAO` — fixo na chave                             |
| IP allowlist | Opcional — restrinja origens                         |

O secret `gp_live_...` aparece **uma vez**. Armazene em secret manager ou `.env` (nunca no Git).

<Warning>
  Não existe chave sandbox. Todas as chaves são de produção; teste com valores baixos.
</Warning>

## Usar na requisição

```bash theme={null}
curl https://api.goatpay.com.br/v1/account/balance \
  -H "X-API-Key: gp_live_SUA_CHAVE"
```

`Authorization: Bearer gp_live_...` ainda funciona por compatibilidade. Prefira `X-API-Key` em código novo.

## Trilho PADRAO

Todas as chaves de API operam no trilho **PADRAO**. PIX, transferência interna e cripto debitam/creditam esse saldo automaticamente — **não** envie `pixRail` no body.

| Trilho     | Quando escolher                                               |
| ---------- | ------------------------------------------------------------- |
| **PADRAO** | Conta verificada; PIX regulado; reembolso, MED, loja e cripto |

## Permissões

Lista completa: [Permissões da API key](/pages/guides/api-permissions).

Princípio do menor privilégio: crie chaves por sistema (ERP, webhook worker, loja) com só o que cada um precisa.

## IP allowlist

Com `allowAnyIp: false`, só IPs/CIDRs cadastrados passam. Requisições de outro IP retornam `403`.

Útil para servidores com IP fixo. Em serverless com IP dinâmico, mantenha `allowAnyIp: true` e proteja o secret.

## Rotacionar chave

1. Crie nova chave com mesmas permissões
2. Atualize variáveis de ambiente nos serviços
3. Teste saldo e uma operação real
4. Revogue a chave antiga no dashboard

## Boas práticas

* Uma chave por ambiente/serviço (não compartilhe entre times)
* Nunca exponha em frontend ou app mobile
* Logs: mascare `gp_live_` (ex. `gp_live_...abc1`)
* Combine com webhooks da mesma chave para receber eventos das transações que ela criou

## Documentação das rotas

[API Reference](/api-reference/overview) · [Rotas da API](/api-reference/escopo-api-publica)