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

# Autenticação

> Como gerar a chave de API e como enviá-la em cada requisição.

A API aceita **dois** tipos de credencial no mesmo header. Para integrações, use a chave
de API; o JWT é o que o painel usa.

| Credencial       | Começa com                     | Para quê                                         | Dura                                                            |
| ---------------- | ------------------------------ | ------------------------------------------------ | --------------------------------------------------------------- |
| **Chave de API** | `v4pay_test_` ou `v4pay_live_` | Integrações — seu sistema chamando a API         | Até você revogar                                                |
| **JWT**          | `eyJ`                          | Sessão do painel; também serve para criar chaves | por padrão **1 hora** (o painel renova sozinho enquanto em uso) |

## Gerar uma chave de API

<Steps>
  <Step title="Faça login para obter um JWT">
    ```bash theme={null}
    curl -X POST https://v4pay-api.vercel.app/auth/login \
      -H "Content-Type: application/json" \
      -d '{ "email": "voce@exemplo.com.br", "password": "sua-senha" }'
    ```

    A resposta traz `data.accessToken`.
  </Step>

  <Step title="Crie a chave">
    ```bash theme={null}
    curl -X POST https://v4pay-api.vercel.app/api-keys \
      -H "Authorization: Bearer SEU_JWT" \
      -H "Content-Type: application/json" \
      -d '{ "name": "ERP da loja", "environment": "live" }'
    ```

    `environment` é `live` (produção) ou `test`. Sem o campo, é produção — e chave de
    produção só existe para conta **aprovada**: antes da
    [aprovação de produção](/aprovacao-de-producao), o pedido com `live` responde `409`
    com `codigo: PRODUCAO_NAO_LIBERADA`. Comece com uma chave de teste
    ([Ambiente de testes](/ambiente-de-testes)).

    ```json theme={null}
    {
      "data": {
        "id": "b7e1…",
        "name": "ERP da loja",
        "prefix": "v4pay_live_3f9a2c1",
        "environment": "live",
        "active": true,
        "key": "v4pay_live_3f9a2c1e8d7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a"
      }
    }
    ```

    <Warning>
      O campo `key` aparece **só nesta resposta**. O V4 Pay guarda apenas um hash; depois
      disso ninguém — nem o suporte — consegue recuperar a chave. Se perder, crie outra.
    </Warning>
  </Step>
</Steps>

## Enviar a chave

Em todas as rotas protegidas, no header `Authorization`, com o prefixo `Bearer`:

```
Authorization: Bearer v4pay_live_3f9a2c1e8d7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a
```

O servidor reconhece a chave pelo prefixo `v4pay_`; qualquer outra coisa é tratada como JWT. O que vem depois — `test_` ou `live_` — é só leitura: o ambiente de verdade está gravado com a chave no servidor, e chaves antigas sem essa marca valem como produção.

## Gerenciar chaves

| Ação                                                               | Rota                                           |
| ------------------------------------------------------------------ | ---------------------------------------------- |
| Listar (mostra só o prefixo e o ambiente; teste e produção juntas) | `GET /api-keys`                                |
| Ativar / desativar                                                 | `PUT /api-keys/{id}` com `{ "active": false }` |
| Revogar de vez                                                     | `DELETE /api-keys/{id}`                        |

Uma chave desativada ou revogada responde `401` com `{ "error": "Chave de API inválida ou revogada" }`.

## Erros de autenticação

Este é o **único** lugar da API onde `error` vem como string, não como objeto:

```json theme={null}
{ "error": "Token JWT ou chave de API ausente" }
```

| Situação                       | Status | Mensagem                            |
| ------------------------------ | ------ | ----------------------------------- |
| Header ausente ou sem `Bearer` | 401    | `Token JWT ou chave de API ausente` |
| Chave desconhecida ou revogada | 401    | `Chave de API inválida ou revogada` |
| JWT inválido ou vencido        | 401    | `Token inválido ou expirado`        |

## Boas práticas

* Uma chave por integração, com um `name` que diga onde ela vive — facilita revogar só a certa.
* Nunca coloque a chave em código de frontend nem em URL. Ela dá controle total da sua loja.
* Guarde em variável de ambiente ou cofre de segredos.