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

# Autenticação na NyxPag API

> Autentique requisições com API Key via Bearer, escolha as permissões certas, entenda cada erro 401 e 403 e proteja suas credenciais.

A NyxPag API autentica cada requisição com uma **API Key** no cabeçalho `Authorization`. Não há login, sessão nem token que expira: a chave vale até você revogá-la.

## Como enviar a chave

```http theme={"dark"}
Authorization: Bearer nyx_live_sua_chave
```

A chave começa com `nyx_live_`. Sem o prefixo `Bearer`, a requisição é recusada.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl https://api.nyxpag.com.br/v1/balance \
    -H "Authorization: Bearer $NYXPAG_API_KEY"
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch("https://api.nyxpag.com.br/v1/balance", {
    headers: { Authorization: `Bearer ${process.env.NYXPAG_API_KEY}` },
  });
  console.log((await res.json()).data);
  ```

  ```python Python theme={"dark"}
  import os
  import requests

  res = requests.get(
      "https://api.nyxpag.com.br/v1/balance",
      headers={"Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}"},
      timeout=15,
  )
  print(res.json()["data"])
  ```

  ```php PHP theme={"dark"}
  <?php
  $ch = curl_init('https://api.nyxpag.com.br/v1/balance');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NYXPAG_API_KEY')],
  ]);
  print_r(json_decode(curl_exec($ch), true)['data']);
  ```
</CodeGroup>

<Warning>
  A chave concede acesso a operações financeiras. Use **somente no servidor**. Nunca em frontend, app mobile, URL, log ou repositório, nem em branch privada.
</Warning>

## Permissões

Cada chave carrega as permissões que você marcou ao criá-la, e cada endpoint exige uma delas.

| Permissão | No dashboard | Libera |
| - | - | - |
| `balance:read` | Saldo | `GET /balance` |
| `payments:write` | Pagamentos | `POST /transactions` |
| `transactions:read` | Transações | `GET /transactions`, `GET /transactions/{id}`, `GET /meds`, `GET /meds/{id}` |
| `transfers:write` | Saques | `POST /transfers` |

Marque só o necessário. Uma chave que apenas cria cobranças no checkout não precisa de `transfers:write`. Se ela vazar, o estrago fica limitado. Veja [combinações recomendadas](/guides/comece-aqui/api-key).

## Erros de autenticação

| HTTP | `error.code` | Causa | Como resolver |
| - | - | - | - |
| `401` | `invalid_api_key` | Chave ausente, mal formada, inexistente ou revogada | Confira o cabeçalho, o prefixo `nyx_` e se a chave segue ativa em **Chaves de API** |
| `403` | `permission_denied` | A chave não tem a permissão do endpoint | A mensagem diz qual (`Permissão necessária: payments:write`). Crie uma nova chave com ela |
| `403` | `ip_not_allowed` | A chave está restrita a IPs e o seu não está na lista | Chame a partir de um IP autorizado |
| `403` | `kyc_required` | A conta ainda não concluiu a verificação de identidade | Conclua a verificação no dashboard |
| `403` | `account_unavailable` | Conta bloqueada ou indisponível | Fale com o suporte |
| `429` | `rate_limit_exceeded` | Passou de 100 requisições em 60 segundos | Veja [Limites](/guides/confiabilidade/limites) |

```json theme={"dark"}
{
  "success": false,
  "error": {
    "code": "permission_denied",
    "message": "Permissão necessária: payments:write."
  },
  "requestId": "req_01H..."
}
```

<Note>
  As requisições já contam para o limite a partir do momento em que a chave e o IP são validados, mesmo quando uma permissão ou validação falha logo depois. Um loop de requisições com erro `403` também gasta a cota.
</Note>

## Gerenciando as chaves

Tudo acontece em [Dashboard → Chaves de API](https://nyxpag.com.br/dashboard/credentials):

* **Nova chave**: escolha o nome e as permissões. A chave completa aparece uma única vez.
* **Renovar chave**: gera um novo valor e **invalida o anterior na hora**. Serve em emergência, não para trocar sem downtime.
* **Revogar chave**: a chave deixa de funcionar imediatamente e as integrações que a usam passam a receber `401`.

Para trocar sem derrubar a integração, siga a [rotação sem indisponibilidade](/guides/comece-aqui/api-key).

## Boas práticas

<Steps>
  <Step title="Uma chave por serviço">
    Checkout, financeiro e painel de leitura usam chaves diferentes. Assim você revoga uma sem afetar as outras.
  </Step>

  <Step title="Permissões mínimas">
    Marque só o que aquele serviço usa.
  </Step>

  <Step title="Cofre de segredos">
    Guarde em variável de ambiente ou num gerenciador de segredos. Nunca no código.
  </Step>

  <Step title="Nunca registre a chave">
    Filtre o cabeçalho `Authorization` de logs, traces e relatórios de erro.
  </Step>

  <Step title="Revogue primeiro, investigue depois">
    Suspeitou de vazamento? Revogue na hora e gere outra.
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="Gestão da API Key" icon="settings" href="/guides/comece-aqui/api-key">
    Permissões por caso de uso, IP allowlist e rotação.
  </Card>

  <Card title="Idempotência" icon="repeat" href="/guides/idempotencia">
    Retentativas seguras nas operações financeiras.
  </Card>
</CardGroup>


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