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

# Authentication

> Como autenticar — API Key ou OAuth — e como funcionam os escopos.

Toda chamada autenticada usa o mesmo header, independente do tipo de token:

```http theme={null}
Authorization: Bearer <token>
```

Existem dois jeitos de conseguir um token. Use o que fizer sentido pro seu caso:

<CardGroup cols={2}>
  <Card title="API Key" icon="key">
    Pra integrar a **sua própria loja** com um sistema interno, script ou app privado. Você mesmo gera a chave no painel — sem fluxo de autorização.
  </Card>

  <Card title="OAuth" icon="plug">
    Pra construir um **app público** que outros vendedores vão instalar e autorizar na loja deles. Veja o [guia de OAuth](/pt/oauth).
  </Card>
</CardGroup>

## API Key

Gerada em **Configurações → API** no painel da Lojou. Cada chave já nasce com um conjunto fixo de escopos, escolhido na hora da criação — não muda depois sem gerar uma chave nova.

```bash theme={null}
curl https://api.lojou.app/v1/orders \
  -H "Authorization: Bearer <sua_api_key>"
```

## Token OAuth

Emitido via `POST /v1/oauth/token`, depois que o vendedor autoriza o seu app. Expira em 30 dias (o `refresh_token` retornado junto serve pra renovar sem pedir autorização de novo — consulte o backend do seu app pra automatizar isso). Os escopos de um token OAuth são os que o **vendedor aprovou** na tela de autorização — podem ser um subconjunto do que o app pediu.

```bash theme={null}
curl https://api.lojou.app/v1/orders \
  -H "Authorization: Bearer <access_token>"
```

Do ponto de vista dos endpoints `/v1/*`, um token OAuth e uma API Key funcionam exatamente igual — a única diferença é como cada um é emitido.

## Escopos

Toda chamada autenticada é validada contra os escopos do token (API Key ou OAuth). Um escopo segue o formato `recurso.ação`:

| Recurso      | Escopos                                                                |
| ------------ | ---------------------------------------------------------------------- |
| `user`       | `user.read` (só leitura — dados do usuário não são editáveis pela API) |
| `products`   | `products.read`, `products.write`                                      |
| `plans`      | `plans.read`, `plans.write`                                            |
| `orders`     | `orders.read`, `orders.write`                                          |
| `customers`  | `customers.read`                                                       |
| `files`      | `files.read`, `files.write`                                            |
| `webhooks`   | `webhooks.read`, `webhooks.write`                                      |
| `discounts`  | `discounts.read`, `discounts.write`                                    |
| `affiliates` | `affiliates.read`, `affiliates.write`                                  |

<Tip>
  Não tem certeza de quais escopos o seu token tem? Chame `GET /v1/scopes` — ele lista todo escopo que existe na API e os endpoints que cada um libera.
</Tip>

Se o escopo necessário estiver ausente, a API responde `403`:

```json theme={null}
{
  "status": "error",
  "message": "Permission denied for this endpoint.",
  "error_code": "insufficient_scope",
  "required_scopes": ["orders.read"],
  "missing_scopes": ["orders.read"],
  "granted_scopes": ["products.read", "products.write"]
}
```

## Erros de autenticação

| Status                   | Motivo                                                            |
| ------------------------ | ----------------------------------------------------------------- |
| `401 Token not provided` | Nenhum header `Authorization` foi enviado.                        |
| `401 Invalid token`      | O token não existe, foi revogado ou expirou.                      |
| `403 insufficient_scope` | O token é válido, mas não tem o escopo exigido por esse endpoint. |