Autenticação na NyxPag API

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

Authorization: Bearer nyx_live_sua_chave

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

curl https://api.nyxpag.com.br/v1/balance \
  -H "Authorization: Bearer $NYXPAG_API_KEY"

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);

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
$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']);

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.

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.

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

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

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.

Gerenciando as chaves

Tudo acontece em Dashboard → Chaves de API:

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.

Boas práticas

Uma chave por serviço

Checkout, financeiro e painel de leitura usam chaves diferentes. Assim você revoga uma sem afetar as outras.

Permissões mínimas

Marque só o que aquele serviço usa.

Cofre de segredos

Guarde em variável de ambiente ou num gerenciador de segredos. Nunca no código.

Nunca registre a chave

Filtre o cabeçalho Authorization de logs, traces e relatórios de erro.

Revogue primeiro, investigue depois

Suspeitou de vazamento? Revogue na hora e gere outra.

Gestão da API Key

Permissões por caso de uso, IP allowlist e rotação.

Idempotência

Retentativas seguras nas operações financeiras.

Comece aqui

Receber

Dinheiro na conta

Disputas

Confiabilidade

Ajuda

Autenticação na NyxPag API

Como enviar a chave

Permissões

Erros de autenticação

Gerenciando as chaves

Boas práticas

Gestão da API Key

Idempotência

​Como enviar a chave

​Permissões

​Erros de autenticação

​Gerenciando as chaves

​Boas práticas

Gestão da API Key

Idempotência

Como enviar a chave

Permissões

Erros de autenticação

Gerenciando as chaves

Boas práticas