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

# Autenticação

> Como autenticar suas requisições com a API key da Z2Pay (header x-api-key).

Toda requisição à API da Z2Pay é autenticada por uma **API key**, enviada no header
**`x-api-key`**.

```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/transactions \
  -H "x-api-key: z2_test_sk_suachavesecreta"
```

<Warning>
  A **secret key** (`sk`) dá acesso total à sua conta. **Nunca** a exponha no frontend, em apps
  mobile, em repositórios públicos ou em logs. Use-a apenas no seu servidor.
</Warning>

## Formato da chave

As chaves seguem o padrão `z2_{ambiente}_{tipo}_{aleatório}` (256 bits de entropia):

```
z2_test_sk_Kx8y9pQ1n3...     secret key de sandbox
z2_live_pk_AbC9dEf2...       publishable key de produção
```

| Parte    | Valores                             | Significado                                                                                                      |
| -------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Ambiente | `test` (sandbox), `live` (produção) | Em qual ambiente a chave funciona. A **mesma** chave vale para todos os produtos (Core, Assinaturas e Checkout). |
| Tipo     | `sk` (secret), `pk` (publishable)   | Nível de acesso.                                                                                                 |

### Secret (`sk`) × Publishable (`pk`)

<CardGroup cols={2}>
  <Card title="Secret key (sk)" icon="lock">
    Acesso completo (criar, ler, atualizar, estornar). **Somente no backend.**
  </Card>

  <Card title="Publishable key (pk)" icon="lock-open">
    Acesso restrito a operações públicas (ex.: tokenização no frontend). Pode ser exposta no
    navegador.
  </Card>
</CardGroup>

## Como obter sua chave

1. Acesse o **Dashboard** da Z2Pay.
2. Para chaves de **teste**, entre no [ambiente de sandbox](/pt-BR/ambientes) e gere as credenciais lá.
3. Para chaves de **produção**, gere no ambiente de produção.
4. Copie a chave **no momento da criação** — por segurança, ela é exibida apenas uma vez (depois fica
   mascarada, ex.: `z2_live_sk_KxY8…3pQ1`).

<Note>
  Uma **única** chave da conta vale para **todos os produtos** — Core, Assinaturas e Checkout ficam
  sob a mesma URL base (`https://api.z2pay.com/v1`) e se distinguem apenas pelo caminho. As chaves
  antigas por produto (`z2_psp_...` / `z2_chk_...`) continuam válidas.
</Note>

<Note>
  Chaves de **sandbox** e de **produção** têm o mesmo formato, mas são geradas em ambientes
  diferentes e **não são intercambiáveis**. Uma chave de sandbox só funciona em `*.sandbox.z2pay.com`.
</Note>

## Respostas de autenticação

| Situação                                        | Status | Resposta                      |
| ----------------------------------------------- | ------ | ----------------------------- |
| Header `x-api-key` ausente ou inválido          | `401`  | `{ "error": "Unauthorized" }` |
| Chave válida, mas sem permissão para a operação | `403`  | `{ "error": "Forbidden" }`    |

<Note>
  **Nos dois casos, `error` é texto, não objeto** — `error.code` é `undefined`. O guard de
  autenticação responde antes de chegar à aplicação, e o envelope `{ error: { code, message } }` é
  dos erros de domínio. Ramifique pelo **status HTTP**. Veja as exceções de formato em
  [Erros](/pt-BR/erros).
</Note>

## Boas práticas

<CardGroup cols={2}>
  <Card title="Use variáveis de ambiente" icon="settings">
    Carregue a chave de uma variável de ambiente/secret manager, nunca hardcoded no código.
  </Card>

  <Card title="Rotacione se vazar" icon="rotate-cw">
    Suspeitou de vazamento? Gere uma nova chave e revogue a antiga no Dashboard.
  </Card>

  <Card title="Uma chave por ambiente" icon="layers">
    Separe claramente as chaves de sandbox e de produção na sua aplicação.
  </Card>

  <Card title="Restrinja no frontend" icon="shield">
    No navegador/app use apenas a `pk`. A `sk` jamais sai do servidor.
  </Card>
</CardGroup>