---
agentTools:
  projectIndex: https://docs.ninepay.com.br/llms.txt
  projectSearch: https://docs.ninepay.com.br/agentSearch?query=term1%20term2
---

# 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`:

```bash
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](/docs/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

1. No dashboard, abra **Integrações** e vá na aba **Chaves de API**.
2. Crie a chave com um nome que diga onde ela é usada (por exemplo, "Site" ou "ERP").
3. Se quiser, escolha uma data e hora de expiração.
4. 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:

1. Gere uma chave nova.
2. Atualize o seu sistema para usar a nova.
3. Desabilite a chave antiga no dashboard.
4. Confira que nada quebrou. Se algo quebrar, reabilite a antiga e volte a investigar.
5. 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.