Permissões e escopo
O que uma chave enxerga depende de três coisas: o cliente a que ela pertence, as contas de anúncio que ela cobre e as permissões do papel dela.
Cliente
Seção intitulada “Cliente”A chave pertence a um único cliente. O identificador dele, tenant_id, vem na resposta da troca de token e vai no caminho de toda leitura: /v1/t/{tenantID}/....
O cliente do caminho é conferido com o do token. Se não bater, a resposta é 403 com TENANT_MISMATCH. Não existe cabeçalho, cookie ou parâmetro que mude de cliente. Para ler dois clientes, use duas chaves, uma de cada.
Contas de anúncio
Seção intitulada “Contas de anúncio”Na criação, a chave recebe uma lista de contas ou vale para todas as do cliente. A troca devolve o resultado no campo accounts:
["*"]significa todas as contas do cliente.- Uma lista de identificadores limita a chave a essas contas.
O limite vale para tudo que a chave lê: totais, séries diárias, campanhas, contas, conversões e o restante. Uma conta fora do escopo não aparece, e os totais não a incluem. Por isso a soma das campanhas que você recebe é o total do seu escopo, não o total do cliente.
Papéis de leitura
Seção intitulada “Papéis de leitura”Uma chave aceita só papéis de leitura. Nenhum deles concede escrita nem execução na plataforma de anúncio.
| Papel | O que acrescenta |
|---|---|
viewer |
Desempenho, contas, plano, criativos e público declarado. Não enxerga orçamento contratado nem alterações retroativas. |
analyst |
Tudo do viewer, mais ritmo de consumo do orçamento (pacing) e alterações retroativas (audit/revisions). |
O papel e as permissões efetivas da sua chave estão nos campos role e permissions da resposta de /v1/token. Confira-os em vez de supor.
Permissão por rota
Seção intitulada “Permissão por rota”Cada rota exige uma permissão. Sem ela, a resposta é 403 com FORBIDDEN.
| Permissão | Rotas |
|---|---|
insights.read |
summary, insights/daily, campaigns, conversions, busca-organica, google-analytics, google-business, merchant-center, sugestoes-de-desempenho |
account.read |
accounts, conexoes |
audit.read |
audit/revisions |
budget.read |
pacing |
plano.read |
plano/funil, plano/vocabulario, plano/acoes |
publico.read |
publicos, publicos/{id}, publicos/taxonomia, publicos/redes |
creative.read |
creatives |
A tabela cobre as rotas que a API responde para chaves de leitura. A Referência traz a permissão de cada rota na descrição dela.
Rotas que omitem blocos
Seção intitulada “Rotas que omitem blocos”A rota summary junta vários blocos numa resposta só. Se a chave não tem a permissão de um bloco (por exemplo, audit.read para as revisões), o bloco é omitido e o campo omitted da resposta lista o que ficou de fora. Isso evita que um papel mais restrito receba 403 na tela inicial e não veja nada.
Quando você consome summary, trate um bloco ausente como “sem permissão”, não como “sem dados”.
Escopo e isolamento na prática
Seção intitulada “Escopo e isolamento na prática”- Para conferir o que a chave cobre, leia
accountsepermissionsna resposta da troca. - Para conferir o frescor de cada conta dentro do escopo, leia
/accounts. - Se você precisa de menos acesso do que a chave tem, crie outra chave com escopo menor. É mais seguro do que filtrar do seu lado.