Proteside API
Crie e revogue os tokens que dão acesso à API pública do Proteside.
Em Configurações → API você cria os tokens que sistemas externos usam para chamar a API do Proteside: um pipeline de CI/CD, um SIEM ou uma automação interna. O token pertence à organização: ele vale para todas as lojas dela e continua funcionando mesmo que quem o criou saia da equipe.
Quem pode gerenciar tokens
Só o proprietário da organização, a pessoa que criou a conta, 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. Se você precisa de um token, peça ao proprietário que crie um com os escopos necessários.
O token é criado para a organização da loja selecionada no seletor de lojas.
Criar um token
Dê um nome
Preencha Nome (1) com algo que identifique a integração, por exemplo "CI de produção". Até 80 caracteres. O nome aparece na lista de tokens.
Escolha os escopos
Os escopos definem o que o token pode fazer. Use os atalhos (2):
- somente leitura: marca os escopos de leitura de lojas, scripts, políticas, alertas, relatórios e uso;
- todos: marca os 15 escopos;
- nenhum: desmarca tudo.
Depois ajuste a lista (3) marcando só o necessário. Por exemplo, uma integração que só leva alertas para o SIEM precisa
apenas de alerts:read. O que cada escopo libera está em Tokens e escopos.
Os escopos não podem ser alterados depois. Para mudar, crie um token novo e revogue o antigo.
Escolha a validade
Em Validade (4), escolha Sem validade, 30 dias, 90 dias ou 365 dias. Um prazo força a troca periódica do token, o que reduz o risco se ele vazar.
Crie e copie
Clique em Criar token (5). A janela Copie o token agora mostra o token completo, que começa com ps_live_.
Clique em Copiar e guarde o token em um cofre de senhas ou de segredos antes de clicar em Concluir.
O token aparece uma única vez
O Proteside não guarda o token completo, só uma impressão dele para conferir as chamadas. Depois que você fecha a janela, não há como ver o token de novo. Se perdê-lo, crie outro e revogue o antigo.
A lista de tokens
Cada token mostra Nome, Prefixo (o início do token, para você reconhecê-lo), Escopos, Último uso, Expira e Status: Ativo, Expirado ou Revogado. Tokens expirados e revogados continuam na lista, esmaecidos, para histórico.
Use a coluna Último uso para descobrir tokens esquecidos: um token que ninguém usa há meses pode ser revogado.
Revogar um token
Clique em Revogar na linha do token e confirme. O efeito é imediato: integrações que usam esse token param de funcionar na próxima chamada. Não é possível desfazer.
Para trocar um token sem interromper uma integração, crie o novo, atualize a integração, confira em Último uso que o antigo parou de ser usado e só então revogue o antigo.
Documentação da API
O link Documentação /developers (2) abre a referência técnica do próprio painel, que está só em inglês. A mesma referência, em português e com exemplos, está nesta documentação:
- Tokens e escopos: como enviar o token e o que cada escopo libera.
- Convenções: paginação, erros e limite de requisições.
- Webhooks: eventos enviados pelo Proteside.