Autenticação

Toda chamada à API da NinePay é autenticada por uma chave de API. Você gera as chaves no dashboard, e elas têm um ciclo de vida automático: as que ficam sem uso são desabilitadas e, depois, expiradas.

Como autenticar

Envie a chave no header Authorization, no formato Bearer:

Shell

curl https://payments.cefis.com.br/api/v1/customers \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json"

Sem a chave, ou com uma chave desabilitada, expirada ou excluída, a API responde 401.

Formato

Prefixo	Ambiente
`sk_prod_…`	Produção
`sk_hmlg_…`	Sandbox

As chaves criadas antes da nova tela de Integrações têm o formato antigo, sem prefixo, e continuam valendo do mesmo jeito. Elas entram no ciclo de vida descrito abaixo como qualquer outra.

Gerando uma chave

No dashboard, abra Integrações e vá na aba Chaves de API.
Crie a chave com um nome que diga onde ela é usada (por exemplo, "Site" ou "ERP").
Se quiser, escolha uma data e hora de expiração.
Copie a chave e guarde num lugar seguro.

A chave aparece uma vez só

Depois de fechar a janela, nem você nem a NinePay conseguem ver a chave de novo, porque guardamos só um hash dela. Se perder, gere outra.

Cada empresa pode ter até 10 chaves.

Trocando uma chave

Troque sem derrubar a integração:

Gere uma chave nova.
Atualize o seu sistema para usar a nova.
Desabilite a chave antiga no dashboard.
Confira que nada quebrou. Se algo quebrar, reabilite a antiga e volte a investigar.
Com tudo funcionando, exclua a chave antiga.

Ciclo de vida automático

Uma chave sem uso passa por estas situações:

Situação	Quando	Dá para voltar?
Habilitada	Em uso, ou sem uso há menos de 3 meses
Desabilitada	3 meses sem uso	Sim, reabilite no dashboard
Expirada	6 meses sem uso	Não, gere uma chave nova

O dono da conta recebe um e-mail 7 dias antes de a chave ser desabilitada por falta de uso e outro no dia. A expiração, seja aos 6 meses sem uso, seja na data que você escolheu, não tem aviso.
Cada chamada autenticada com a chave conta como uso e reinicia a contagem.
Se você definiu uma data de expiração, a chave para de funcionar nela, independentemente de uso.

Boas práticas

Nunca coloque a chave em código que roda no navegador nem em aplicativo móvel: quem baixar o app ou abrir o código-fonte da página consegue lê-la. Chame a API a partir do seu servidor.
Guarde a chave em variável de ambiente (como NINEPAY_TOKEN nos exemplos), não no código nem no repositório.
Use uma chave por integração. Assim você desabilita ou troca uma sem afetar as outras, e vê quais estão em uso.
Se suspeitar que uma chave vazou, desabilite-a e gere outra.