Escopos definem exatamente o que um token pode fazer. Ao criar um token, você escolhe um conjunto de escopos, e o token só pode acessar os endpoints cobertos por essas permissões. Essa granularidade segue o princípio de menor privilégio: um token que só precisa ler produtos nunca deve ter permissão para criá-los. Isso limita o raio de impacto em caso de vazamento e facilita a auditoria de acessos.
Escopos disponíveis
cashouts:read dá acesso a dado financeiro (saques). Conceda-o apenas a tokens que realmente precisem, de preferência em um token separado dos demais.
subscriptions:cancel é o único escopo destrutivo da API: ele cancela assinaturas de verdade, e não há como desfazer.Por isso ele é tratado de forma diferente dos demais:
- Nunca vem junto. Um token com escopo amplo não recebe
subscriptions:cancel por tabela. Ele precisa ser pedido nominalmente na criação do token.
- Limites próprios. A rota de cancelamento aceita 5 requisições por minuto e 50 por dia, bem abaixo do resto da API.
- Proteção contra varredura. Um token que acumula respostas
404 nessa rota (tentando id que não existe ou não é seu) é bloqueado temporariamente nela.
Recomendação: mantenha o cancelamento em um token separado, usado só por esse fluxo.Quais escopos cada endpoint exige
Crie tokens separados para leitura e escrita. Se o token de leitura vazar, sua conta não corre risco de criação fraudulenta de produtos, ele simplesmente não tem essa permissão.
Erro de escopo insuficiente
Quando um token válido tenta acessar um endpoint para o qual não possui o escopo necessário, a API retorna 403 Forbidden com o seguinte corpo:
Para corrigir, verifique quais escopos o endpoint exige (tabela acima) e gere um novo token com as permissões adequadas, ou adicione o escopo ao token existente no painel em Integrações → API v2. 
