# Tokens e escopos

> Crie tokens da API em Configurações → API, escolha os escopos certos e envie o token no header Authorization.

URL: https://docs.proteside.com/pt-BR/docs/api/authentication

Toda chamada à API (exceto o documento OpenAPI) precisa de um token. O token pertence à **organização**, não a um
usuário nem a uma loja: ele vale para todas as lojas da organização e continua funcionando se quem o criou sair da
equipe.

## Criar um token
Só o **proprietário da organização** cria e revoga tokens. Os demais papéis veem o aviso "Somente o proprietário da
organização pode gerenciar tokens." no lugar da lista.

### Abra a tela de tokens
No seletor de lojas, escolha uma loja da organização que vai usar o token. Depois abra **Configurações → API**. O
token é criado para a organização da loja selecionada.

### Clique em Novo token
Clique em **Novo token** no canto superior direito.

### Dê um nome
Preencha **Nome** com algo que identifique a integração, por exemplo "CI de produção" ou "SIEM". O nome aceita até
80 caracteres e aparece na lista e na auditoria.

### Marque os escopos
Em **Escopos**, marque só o que a integração precisa. Os atalhos **somente leitura**, **todos** e **nenhum** ajudam a
começar. É obrigatório marcar pelo menos um. Os escopos não podem ser alterados depois: para mudar, crie outro token.

### Escolha a validade
Em **Validade**, escolha **Sem validade**, **30 dias**, **90 dias** ou **365 dias**. Depois do prazo, o token passa a
responder `401 Token expired`.

### Copie o token
Clique em **Criar token**. Na janela **Copie o token agora**, clique em **Copiar** e guarde o token num cofre de
segredos antes de clicar em **Concluir**.

> **O token aparece uma única vez**
>
> O Proteside guarda só um hash do token. Se você fechar a janela sem copiar, não há como recuperá-lo: revogue e crie
> outro.

*Imagem: A lista mostra o prefixo de cada token, os escopos, o último uso e o status (Ativo, Expirado ou Revogado).*

> **Proprietário da loja não é o mesmo que proprietário da organização**
>
> A tela mostra o botão **Novo token** para quem é proprietário da loja selecionada, mas a criação exige ser
> proprietário da **organização**. Se você vir o erro "Somente o proprietário da organização pode gerenciar tokens."
> ao clicar em **Criar token**, peça ao proprietário da organização para criar o token.

## Usar o token
O token tem o formato `ps_live_` + 24 caracteres + `_` + 32 caracteres (65 no total). Envie-o no header
`Authorization` de toda requisição:

```bash
curl -s "https://app.proteside.com/api/v1/stores" \
  -H "Authorization: Bearer ps_live_SEU_TOKEN"
```

Os primeiros 32 caracteres (`ps_live_` + 24) são o **prefixo**: é o que aparece na coluna **Prefixo** da lista e nos
registros de auditoria das ações feitas pela API (`api:ps_live_SEU_PREFIXO`).

Quando o token falha, a API responde `401` com o header `WWW-Authenticate: Bearer realm="proteside-api"` e uma destas
mensagens:

| `message`                           | Causa                                                 |
| ----------------------------------- | ----------------------------------------------------- |
| `Missing or malformed bearer token` | Header ausente, sem `Bearer` ou token fora do formato |
| `Invalid token`                     | Token inexistente ou revogado                         |
| `Token expired`                     | Prazo de validade vencido                             |

A coluna **Último uso** é atualizada no máximo uma vez por minuto por token.

## Escopos
Cada endpoint exige **exatamente um** escopo. Não há hierarquia: `stores:write` não inclui `stores:read`, então uma
integração que cria e depois consulta lojas precisa dos dois. Sem o escopo, a resposta é
`403 insufficient_scope`.

| Escopo             | O que libera                                                                                                                                  |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `stores:read`      | `GET /stores`, `GET /stores/{id}`, `GET /stores/{id}/status`, `GET /stores/{id}/pages`                                                        |
| `stores:write`     | `POST /stores`, `PATCH /stores/{id}`, `DELETE /stores/{id}` (suspende), `POST /stores/{id}/rotate-key`                                        |
| `pages:write`      | `POST /stores/{id}/pages`                                                                                                                     |
| `scripts:read`     | `GET /scripts` e `GET /rules`                                                                                                                 |
| `scripts:review`   | `POST /scripts/{id}/authorize`, `POST /scripts/{id}/block`                                                                                    |
| `rules:write`      | `POST /rules`, `PATCH /rules/{id}`, `DELETE /rules/{id}`, `DELETE /rules?id=`                                                                 |
| `policies:read`    | `GET /policies`, `POST /policies/{id}/simulate`                                                                                               |
| `policies:write`   | `POST /policies`, `PATCH /policies/{id}`, `DELETE /policies/{id}`, `POST /policies/{id}/apply`                                                |
| `alerts:read`      | `GET /alerts`, `GET /alerts/{id}`                                                                                                             |
| `alerts:write`     | `PATCH /alerts/{id}` (resolver e reabrir)                                                                                                     |
| `reports:read`     | `GET /reports/pci`, `GET /reports/pci/snapshots`, `GET /reports/pci/snapshots/{id}`, `GET /reports/pci/schedule`                              |
| `reports:generate` | `POST /reports/pci/schedule`, `DELETE /reports/pci/schedule`; também é exigido junto com `reports:read` em `GET /reports/pci?regenerate=true` |
| `webhooks:manage`  | Todos os endpoints `/webhooks`, inclusive leitura e teste                                                                                     |
| `orgs:manage`      | `GET /organizations`, `POST /organizations` e o uso de `org_id` para agir numa organização filha ([Parceiros](https://docs.proteside.com/pt-BR/docs/api/partners))                |
| `usage:read`       | `GET /organizations/{id}/usage`                                                                                                               |

O atalho **somente leitura** marca `stores:read`, `scripts:read`, `policies:read`, `alerts:read`, `reports:read` e
`usage:read`.

> **Listar regras exige scripts:read**
>
> O spec OpenAPI descreve `stores:read` como o escopo de leitura de regras, mas `GET /rules` exige `scripts:read`.
> Se a sua integração lista regras, inclua `scripts:read` no token.

> **Leitura que gera dados**
>
> `GET /reports/pci` sem `period_start` e `period_end` gera um relatório novo a cada chamada, mesmo com um token só de
> leitura. Veja [Receitas](https://docs.proteside.com/pt-BR/docs/api/recipes#baixar-o-relat%C3%B3rio-pci-dss-em-pdf) para baixar relatórios sem gerar cópias.

## Revogar um token
Em **Configurações → API**, clique em **Revogar** na linha do token e confirme. O efeito é imediato: a próxima
chamada com esse token recebe `401 Invalid token`. O token continua na lista com o status **Revogado**, para
histórico.

Não existe endpoint na API para criar, listar ou revogar tokens: isso só é feito pelo dashboard.

## Boas práticas
* **Um token por integração.** Assim você revoga uma sem derrubar as outras, e a auditoria mostra qual sistema fez
  cada alteração.
* **Menor privilégio.** Um coletor de alertas para o SIEM precisa só de `alerts:read`. Um pipeline que só baixa
  relatórios precisa só de `reports:read`.
* **Guarde em um cofre de segredos** (AWS Secrets Manager, GCP Secret Manager, Vault, variáveis protegidas do CI).
  Nunca coloque o token em código-fonte, no front-end ou em logs.
* **Rotacione com sobreposição.** Crie o token novo, atualize a integração, confirme na coluna **Último uso** que o
  antigo parou de ser usado e só então revogue o antigo. Prefira validade de 90 ou 365 dias para forçar a rotação.
* **Revogue ao menor sinal de vazamento.** O token dá acesso a todas as lojas da organização.

## Próximos passos
- [Convenções](https://docs.proteside.com/pt-BR/docs/api/conventions): Paginação, erros, limite de requisições e idempotência.
- [Tokens no dashboard](https://docs.proteside.com/pt-BR/docs/guide/settings/api-tokens): A tela Configurações → API em detalhe.
