# API

> Crie e revogue os tokens da API pública do Proteside: quem pode gerenciar, como escolher os escopos e a validade de cada token.

URL: https://docs.proteside.com/pt-BR/docs/guide/settings/api-tokens

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.

*Imagem: A tela API antes do primeiro token.*

## 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
### Abra o formulário
Clique em **Novo token** (1).

*Imagem: Janela Novo 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](https://docs.proteside.com/pt-BR/docs/api/authentication#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 **Abrir a documentação da API** (2) abre, em nova aba, a seção de API desta documentação, no idioma do painel.
Os pontos de partida são:

* [Tokens e escopos](https://docs.proteside.com/pt-BR/docs/api/authentication): como enviar o token e o que cada escopo libera.
* [Convenções](https://docs.proteside.com/pt-BR/docs/api/conventions): paginação, erros e limite de requisições.
* [Webhooks](https://docs.proteside.com/pt-BR/docs/api/webhooks): eventos enviados pelo Proteside.

## Próximos passos
- [Tokens e escopos](https://docs.proteside.com/pt-BR/docs/api/authentication): Use o token nas chamadas e escolha os escopos certos.
- [Receitas](https://docs.proteside.com/pt-BR/docs/api/recipes): Exemplos prontos de integração.
