Chaves de API

Aprenda como funcionam as chaves de API e como utilizá-las para acessar a Nucleo Pay.

A chave de API é sua credencial de acesso à Nucleo Pay. Ela identifica sua conta e autoriza cada requisição enviada para a nossa API. Sem uma chave válida, nenhum pedido será aceito.

O que você pode fazer com suas chaves

As chaves de API são gerenciadas diretamente pelo painel. Com elas, você pode:

Ver todas as chaves ativas
Criar novas chaves para diferentes projetos (bot, site, backend)
Renomear, rotacionar ou revogar chaves comprometidas

Teste vs Produção

Mesma base URL https://nucleopay.com.br. O ambiente é a chave:

np_test_… — sandbox (PIX fake, simulate-pay, livemode: false)
ncp_prod_… — produção (PIX real)

Crie token de teste com {"label":"dev","mode":"test"} em POST /api/auth/token/create.

Erro de Autenticação (401)

Você receberá um HTTP 401 quando: a chave não for enviada no header, a chave estiver incorreta ou a chave tiver sido revogada.

Como enviar a chave

Toda requisição deve incluir o header Authorization:

Authorization: Bearer SUA_CHAVE_API

Boas práticas de segurança

Armazene suas chaves em variáveis de ambiente
Nunca publique sua chave em repositórios ou grupos
A Nucleo Pay nunca solicitará sua chave por mensagem
Revogue imediatamente qualquer chave que possa ter vazado

Como criar uma chave de API

Acesse o painel
Entre em nucleopay.com.br/app e vá em API e Webhooks.
Clique em "Novo token"
Inicie a criação de uma nova chave de API.
Adicione uma descrição
Use nomes claros, como "Bot Telegram" ou "Loja principal".
Copie a chave gerada
Copie e salve em um local seguro ou gerenciador de segredos. Ela não será exibida novamente.

Depois disso, você já pode enviar requisições:

curl -X POST https://nucleopay.com.br/api/pix/charge/create \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  --data '{
    "value": 49.90,
    "title": "Meu produto"
  }'

Endpoint de criação de token: POST /api/auth/token/create com body { "label": "Nome do token" } — requer autenticação Bearer existente.