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

# Autenticação

> API Key, escopos e lojas permitidas.

Todas as rotas `/api/v1` pedem API Key da Corvex.

```http theme={null}
Authorization: Bearer cvx_live_YOUR_API_KEY
X-Store-Id: 11111111-1111-4111-8111-111111111111
Content-Type: application/json
```

A chave começa com `cvx_live_` e nasce no **painel**. Não é JWT de sessão nem `x-api-key` do checkout.

<Warning>
  Trate a chave como senha. Não commite, não exponha no browser e não cole em tickets. Se vazar, revogue e crie outra.
</Warning>

## Escopos

Peça só o que a integração precisa.

| Escopo                                               | Uso                                                     |
| ---------------------------------------------------- | ------------------------------------------------------- |
| `products:read` / `products:write`                   | Produtos                                                |
| `categories:read` / `categories:write`               | Coleções                                                |
| `kits:read` / `kits:write`                           | Kits                                                    |
| `orders:read`                                        | Pedidos e listagem de rastreio                          |
| `orders:write`                                       | Atualizar status, rastreio, tags e anotações            |
| `customers:read`                                     | Clientes                                                |
| `abandoned-carts:read`                               | Carrinhos abandonados                                   |
| `leads:read`                                         | Leads                                                   |
| `order-bumps:read` / `order-bumps:write`             | Order bumps                                             |
| `gifts:read` / `gifts:write`                         | Brindes de checkout                                     |
| `upsells:read` / `upsells:write`                     | Upsell one-click                                        |
| `coupons:read` / `coupons:write`                     | Cupons                                                  |
| `discount-ranges:read` / `discount-ranges:write`     | Faixas de desconto                                      |
| `payment-discounts:read` / `payment-discounts:write` | Desconto por forma de pagamento                         |
| `webhooks:read` / `webhooks:write`                   | Webhooks                                                |
| `automations:read`                                   | Metatags, automações e templates (leitura)              |
| `automations:write`                                  | Validar, criar, editar e excluir automações e templates |

Leitura não escreve. Escrita de catálogo não lista. Peça só o que a integração precisa.

## Lojas permitidas

Na criação da chave você informa `storeIds`. A integração só acessa essas lojas.

Se `X-Store-Id` apontar para uma loja fora da lista → `403 AUTH_STORE_ACCESS_DENIED`. Sem o header, ou UUID inválido → `400 VALIDATION_ERROR`.

## Erros de autenticação

| HTTP  | Código                     | O que fazer                                       |
| ----- | -------------------------- | ------------------------------------------------- |
| `401` | `AUTH_API_KEY_REQUIRED`    | Faltou o header, ou você enviou JWT / `x-api-key` |
| `401` | `AUTH_API_KEY_INVALID`     | Chave malformada ou inexistente                   |
| `401` | `AUTH_API_KEY_EXPIRED`     | Crie uma chave nova no painel                     |
| `401` | `AUTH_API_KEY_REVOKED`     | A chave foi revogada                              |
| `403` | `AUTH_SCOPE_DENIED`        | Falta o escopo da operação                        |
| `403` | `AUTH_STORE_ACCESS_DENIED` | Loja não está na chave                            |

<AccordionGroup>
  <Accordion title="Posso usar o token do painel?" icon="circle-help">
    Não. `/api/v1` recusa JWT de sessão de propósito: a superfície de integração é só API Key.
  </Accordion>

  <Accordion title="A chave some se eu recarregar o painel?" icon="eye-off">
    O valor completo só aparece na criação. Depois você vê um recorte (`cvx_live_ABCD…WXYZ`). Se não guardou, revogue e gere outra.
  </Accordion>
</AccordionGroup>