Proteside Tokens e escopos
Crie tokens da API em Configurações → API, escolha os escopos certos e envie o token no header Authorization.
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.
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:
curl -s "https://app.proteside.com/api/v1/stores" \
-H "Authorization: Bearer ps_live_Ab3dEf6hIj9kLm2nOp5qRs8t_..."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_Ab3dEf6hIj9kLm2nOp5qRs8t).
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) |
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 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ó dereports: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.