> ## Documentation Index
> Fetch the complete documentation index at: https://docs.purin.cash/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.purin.cash` 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

**1. Abra o painel**

[purin.cash/dashboard/api](https://purin.cash/dashboard/api)

**2. Escolha o ambiente**

Produção gera `ps_live_`. Sandbox gera `ps_test_`.

**3. Copie na hora**

A chave completa aparece uma vez só. Depois disso o painel mostra apenas os últimos
caracteres, para você identificar qual é qual.

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](https://docs.purin.cash/guias/ambientes.md).

## Guardando a chave

> [!WARNING]
>
> Quem tem a sua chave consegue criar cobrança em seu nome e, com [PIX saindo na
> hora](https://docs.purin.cash/guias/saques.md#quando-o-pix-sai-na-hora), mandar dinheiro pra fora sem passar por aprovação.
> Trate a chave com o mesmo cuidado da senha do painel.

> [card] Faça
>
> 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] Não faça
>
> 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".

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.