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

# Autenticação

> Uma chave, um header. Como pegar, como guardar e o que fazer quando vaza.

Toda requisição para `https://api.purincash.com` leva a chave de API no header
`Authorization`, no esquema Bearer:

```
Authorization: Bearer ps_live_sua_chave_aqui
```

Não existe OAuth, não existe login por usuário e senha na API, e não existe chave no
query string.

## Pegando a chave

<Steps>
  <Step title="Abra o painel">
    [purincash.com/dashboard/api](https://purincash.com/dashboard/api)
  </Step>

  <Step title="Escolha o ambiente">
    Produção gera `ps_live_`. Sandbox gera `ps_test_`.
  </Step>

  <Step title="Copie na hora">
    A chave completa aparece uma vez só. Depois disso o painel mostra apenas os últimos
    caracteres, para você identificar qual é qual.
  </Step>
</Steps>

Cada conta pode manter até 10 chaves ativas ao mesmo tempo. Use isso a seu favor: uma
chave por ambiente e por serviço deixa você revogar uma sem derrubar o resto.

## O prefixo define o ambiente

| Prefixo    | Ambiente | O que acontece                           |
| ---------- | -------- | ---------------------------------------- |
| `ps_live_` | Produção | Cobrança real, dinheiro real, saldo real |
| `ps_test_` | Sandbox  | Tudo simulado, nada movimenta dinheiro   |

Não existe parâmetro de ambiente. A chave decide, e os dados são isolados: uma chave de
teste nunca lista uma cobrança de produção. Mais detalhes em [Ambientes e
sandbox](/guias/ambientes).

## Guardando a chave

<Warning>
  Quem tem a sua chave consegue criar cobrança em seu nome e, com [saque
  turbo](/guias/saques#saque-turbo), mandar dinheiro pra fora sem passar por aprovação.
  Trate a chave com o mesmo cuidado da senha do painel.
</Warning>

<CardGroup cols={2}>
  <Card title="Faça" icon="circle-check" color="#10b981">
    Variável de ambiente ou cofre de segredos.

    Chamada sempre de servidor pra servidor.

    Uma chave por serviço, para revogar sem parar tudo.

    `ps_test_` no desenvolvimento e na CI.
  </Card>

  <Card title="Não faça" icon="circle-xmark" color="#ef4444">
    Chave no bundle do front, no app mobile ou no `.env` versionado.

    Chave em log, em print, em ticket de suporte.

    A mesma chave em produção e homologação.

    Chave hardcoded "só pra testar rápido".
  </Card>
</CardGroup>

Se desconfiar que vazou, revogue no painel e gere outra. A revogação vale na hora: a
chave antiga passa a responder `401` na requisição seguinte.

## Erros de autenticação

Todos vêm como `401` com o corpo padrão `{ "error": string }`.

| Mensagem                                                   | O que aconteceu                                                            |
| ---------------------------------------------------------- | -------------------------------------------------------------------------- |
| `API key required. Use: Authorization: Bearer ps_live_...` | Header ausente, ou sem o `Bearer ps_` na frente                            |
| `Invalid API key prefix. Use ps_live_ or ps_test_`         | A chave não começa com nenhum dos dois prefixos                            |
| `Invalid or revoked API key`                               | Chave inexistente, digitada errada ou revogada                             |
| `API key environment mismatch. Please generate a new key.` | O prefixo não bate com o ambiente em que a chave foi criada. Gere uma nova |

```json theme={null}
{ "error": "Invalid or revoked API key" }
```

<Tip>
  Recebeu `401` com a chave certa? Confira se sobrou espaço, quebra de linha ou aspas na
  variável de ambiente. É de longe a causa mais comum.
</Tip>