Escopos

Escopo é a permissão que o administrador concede a um aplicativo no consentimento. Todos os escopos da versão 1 são de leitura: um aplicativo não altera nada na owiew, e nenhum escopo permite escrita em plataforma de anúncio.

Formato

Um escopo tem o formato recurso:read, em minúsculas (por exemplo, metricas:read). Ele aparece:

• no campo scp do token de app, como lista;
• no campo scope da resposta do endpoint de token, separado por espaço;
• no campo escopos da resposta de GET /apps/v1/instalacao.

Catálogo

Escopo	O que o administrador autoriza	Risco	Dados pessoais	Estado
instalacao:read	Ver em qual projeto o aplicativo está instalado e quais permissões ele recebeu.	Baixo	Não	Disponível
metricas:read	Receber e ler o resultado diário consolidado das redes de anúncio de cada projeto consentido.	Baixo	Não	Planejado
conversoes:read	Receber e ler as conversões registradas em cada projeto consentido, sem dados pessoais do comprador.	Médio	Não	Planejado
relatorios:read	Receber o aviso e o link de cada relatório publicado nos projetos consentidos. O link abre sem login: quem o recebe passa a poder abri-lo.	Alto	Não	Planejado

O texto da coluna “O que o administrador autoriza” é o texto literal exibido na tela de consentimento. Se o sentido de um escopo mudasse, ele ganharia um identificador novo. Um escopo já publicado não muda de texto, risco ou classificação de dados pessoais.

Os três escopos marcados como planejado dependem dos eventos correspondentes (veja eventos e webhooks). Eles já existem no catálogo, mas só passam a valer para assinatura quando os eventos forem liberados.

Regras

1. instalacao:read é implícito. Toda instalação o recebe. A tela de consentimento o lista como informativo, sem opção de desmarcar.
2. O escopo efetivo é a interseção de três conjuntos: o que o administrador concedeu, o que está ativo no catálogo e o que a versão do aplicativo declara. Retirar um escopo do catálogo corta todos os aplicativos no próximo token, em até 2 minutos.
3. Pedir mais escopo exige versão nova. Subir escopo cria uma versão do aplicativo e um novo consentimento. Enquanto isso, a instalação continua com os escopos antigos.
4. O administrador só concede o que ele mesmo pode ver. Cada escopo corresponde a uma permissão do administrador no projeto. Se ele não tem a permissão equivalente em algum dos projetos escolhidos, não consegue conceder o escopo.
5. O escopo pertence à instalação, não ao projeto. Todos os projetos consentidos compartilham os mesmos escopos. O recorte por projeto vem do token e do campo projeto_id do evento.
6. Um escopo serve aos dois sentidos. O mesmo escopo autoriza a rota de API que o exige e o evento de webhook que o exige.

Escopo insuficiente

Chamar uma rota sem o escopo exigido devolve 403 com o código escopo-insuficiente e o nome do escopo que faltou. Para inscrever um evento sem o escopo na instalação, o cadastro da inscrição responde 422 com escopo-ausente-para-evento.

Próximos passos

• Instalação e consentimento
• API de apps /apps/v1
• Eventos e webhooks