# Autenticação

Toda chamada à API leva a chave no cabeçalho `Authorization`, no formato Bearer.

_curl_

```bash
curl https://stacepay.com.br/api/v1/account \
  -H "Authorization: Bearer nvx_live_..."
```

```js
fetch('https://stacepay.com.br/api/v1/account', {
  headers: { Authorization: 'Bearer nvx_live_...' }
})
```

```php
$ch = curl_init('https://stacepay.com.br/api/v1/account');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer nvx_live_...']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
```

## Gerando uma chave

Em [Painel → Integrações](https://stacepay.com.br/painel/integracoes), clique em "Gerar chave". O valor completo (prefixo `nvx_live_`) só aparece uma vez, no momento da criação copie e guarde num cofre de segredos. Depois disso, só o painel identifica a chave pelos primeiros caracteres.

> 🚫 Uma chave revogada nunca volta a funcionar. Se ela vazar, revogue e gere outra chamadas com a chave antiga passam a devolver `401 revoked_api_key`.

## Contas ainda não verificadas

Ler dados (`GET`) funciona com qualquer chave válida. Operações que movimentam dinheiro criar cobrança e criar saque exigem que o KYC da conta esteja aprovado; sem isso a API devolve `403 kyc_required`.

## Limites de requisição

| Situação | Limite |
| --- | --- |
| Sem autenticar (por IP) | 20 req/min |
| Autenticado, leitura | 300 req/min por chave |
| Autenticado, escrita (POST/PUT/DELETE) | 60 req/min por chave |

Ao estourar, a resposta é `429 rate_limit_exceeded` com o cabeçalho `Retry-After` indicando quantos segundos esperar.