Os 15 scopes para chaves de API e ligações de IA: o que cada scope permite, como se chama no painel e o que nenhuma chave de API pode fazer.
Os scopes definem o que uma chave de API pode fazer. Os mesmos 15 scopes aplicam-se também aos assistentes de IA que liga via MCP. Escolha sempre apenas os scopes de que uma aplicação precisa realmente.
Regras básicas
- Cada endpoint exige exatamente um scope
- Nas chaves de API, write:X inclui automaticamente read:X – o painel indica «write:X inclui automaticamente read:X»
- Se faltar o scope, a API responde com 403 insufficient_scope e indica o scope necessário em details.required_scope
- Os endpoints que não estão de todo disponíveis para chaves de API também respondem com 403 insufficient_scope
- As funções de proprietário e admin, como membros, faturação ou gestão de domínios, não ficam acessíveis com nenhum scope
Todos os scopes
Na caixa de diálogo «Criar nova chave de API» escolhe «Leitura» ou «Escrita» para cada área; a lista de chaves mostra os nomes dos scopes da primeira coluna. A forma «Leitura · Páginas» aparece na página de consentimento das apps de IA e em «Apps ligadas».
| Scope | Para apps de IA | Permite |
|---|---|---|
| read:pages | Leitura · Páginas | Listar e ler páginas, ler e validar o rascunho, listar blocos, ler o SEO, listar versões, obter os tipos de bloco |
| write:pages | Escrita · Páginas | Criar e editar páginas (incluindo o handle), editar o rascunho, criar, editar, eliminar e reordenar blocos, editar o SEO, visibilidade, publicação, restaurar uma versão, links de convite para páginas privadas |
| read:links | Leitura · Links | Listar e ler os links de uma página |
| write:links | Escrita · Links | Criar, editar, eliminar e reordenar links |
| read:assets | Leitura · Ficheiros | Listar ficheiros |
| write:assets | Escrita · Ficheiros | Carregar e eliminar ficheiros, carregamentos para uma página |
| read:forms | Leitura · Formulários | Ler formulários, resumo, listar submissões e exportá-las como CSV (exportação a partir do Creator Pro) |
| write:forms | Escrita · Formulários | Criar, editar e eliminar formulários |
| read:stats | Leitura · Estatísticas | Estatísticas da página e do espaço de trabalho (resumo, série temporal, comparação, links, widgets, conversões, páginas principais), histórico de push e utilização de push |
| read:workspaces | Leitura · Espaços de trabalho | Ler as funcionalidades do plano, a utilização, a lista de membros e as definições do espaço de trabalho, listar domínios, listar e ler modelos, listar e ler segredos de callback (sem o segredo em texto simples) |
| write:workspaces | Escrita · Espaços de trabalho | De momento, sem endpoints além dos de read:workspaces |
| read:donations | Leitura · Pagamentos de apoiantes | Totais dos pagamentos de apoiantes do espaço de trabalho (pagamentos através do bloco «Apoiar») |
| read:short_links | Leitura · Links curtos | Listar e ler links curtos |
| write:short_links | Escrita · Links curtos | Criar, editar e eliminar links curtos |
| write:templates | Escrita · Modelos do espaço de trabalho | Criar, editar e eliminar os seus próprios modelos do espaço de trabalho (são lidos com read:workspaces), veja Modelos próprios |
Os endpoints exatos que pertencem a cada scope estão em Endpoints por área.
O que nenhuma chave de API pode fazer
- Eliminar páginas
- Criar links de pré-visualização para o rascunho
- Detalhes das estatísticas por dispositivo, país, referenciador e UTM
- Enviar notificações push e gerir regras de push
- Ligar ou desligar integrações
- Gerir webhooks
- Adicionar, verificar, ativar, desativar ou eliminar domínios
- Gerir membros, convites e funções, transferir a propriedade
- Alterar as definições do espaço de trabalho, faturação
- Criar, editar, rodar ou eliminar segredos de callback
- A lista de pagamentos de apoiantes, pedidos de acesso a dados e anonimizar submissões de formulários
- Gerir o seu perfil, as páginas que segue e as próprias chaves de API
Estas ações são feitas no painel.
Scopes para assistentes de IA
Numa ligação MCP escolhe os mesmos scopes na página de consentimento. Há duas diferenças: em primeiro lugar, uma permissão de escrita aí não inclui a permissão de leitura – por isso, conceda ambas. Em segundo lugar, a sua função limita a escolha: os leitores só recebem permissões de leitura (sem formulários e links curtos), os editores recebem tudo exceto «Escrita · Espaços de trabalho», links curtos e modelos do espaço de trabalho. Mais informações em Permissões, segurança e limites.
Combinações recomendadas
| Caso de utilização | Scopes |
|---|---|
| Relatórios e dashboards | read:stats, read:pages |
| Sincronizar links a partir de um CMS ou de uma loja | write:links, read:pages |
| Manter e publicar páginas automaticamente | write:pages, write:links |
| Links de campanha a partir do CRM | write:short_links |
| Passar leads dos formulários para o CRM | read:forms |
| Implementar modelos a partir de um pipeline de CI | write:templates, read:workspaces |
Também lhe pode ser útil
Não encontrou o que procura?
Diga-nos de que precisa e a nossa equipa de suporte ajuda-o pessoalmente.