Âmbitos da API e permissões dos planos

Os âmbitos controlam exatamente o que um token de API pode fazer. Cada token contém um conjunto de âmbitos, que a API verifica em todos os pedidos.

Como funcionam os âmbitos

Ao criar um token, seleciona os âmbitos a incluir. A API aplica três limites máximos a cada pedido:

Direitos da conta: o plano atual e os add-ons ativos determinam as capacidades que existem nesse momento.
Associação: uma pessoa com acesso delegado não pode conceder nem usar mais do que a sua função atual e o seu acesso a domínios permitem.
Concessão da credencial: o token ou consentimento OAuth deve incluir o âmbito exigido pelo endpoint.

O erro identifica o limite que falhou. insufficient_scope significa que o âmbito nunca foi concedido à credencial, scope_blocked_by_membership significa que a função da pessoa é mais restrita e scope_blocked_by_entitlement significa que o direito White Label necessário não está ativo.

Duas camadas de âmbitos: OAuth e âmbitos da API

OAuth suporta seis grupos legados convenientes, todos os âmbitos granulares da API e seletores tools:* que controlam apenas a exposição. Os grupos legados são:

Âmbito OAuth	Abrange
`mail:read`	Ler conta, domínios, caixas de correio, reencaminhamento, regras de correio, resposta automática, SMTP, Cloudflare e pedidos de suporte, além da leitura do Drive.
`mail:write`	Todo o `mail:read`, mais criação, atualização e eliminação de domínios, caixas, aliases, reencaminhamento, regras, resposta automática, DNS do Cloudflare, pedidos de suporte, carregamentos e partilhas do Drive.
`mail:admin`	Todo o `mail:write`, mais faturação, intenções de eliminação, purgas destrutivas do Drive, escrita de migrações, eliminação de tokens Cloudflare e emissão de tokens de mensagens.
`messages:read`	Ler o conteúdo das caixas (mensagens, pastas, anexos, contactos, calendário, identidades e modelos).
`messages:write`	Alterar rascunhos, pastas, indicadores, contactos, calendários, modelos e definições sem enviar correio.
`messages:send`	Ler e enviar correio, incluindo criar rascunhos e agendar mensagens.

Cada grupo OAuth legado expande-se em âmbitos granulares da API, como domains:read e drive:account:write. As novas integrações podem pedir diretamente esses âmbitos. Os âmbitos White Label foram deliberadamente excluídos dos grupos mail:* antigos, pelo que um conector existente nunca obtém administração de revenda após uma atualização. Tem de pedir explicitamente os âmbitos White Label necessários. Um seletor tools:white_label limita a exposição no MCP, mas não concede por si só permissões da API.

Três formas de ligação e como cada uma concede capacidades

Existem três formas de um agente ou integração chegar ao TrekMail, e o mecanismo de controlo é diferente em cada uma. Isto é importante porque os "indicadores de capacidades" do MCP (TREKMAIL_ALLOW_DESTRUCTIVE, TREKMAIL_ALLOW_SENDING, TREKMAIL_ALLOW_MIGRATION) existem apenas numa delas.

Modo	Autenticação	Mecanismo de controlo	Indicadores de capacidades	Alcance de ferramentas/endpoints
MCP HTTP alojado (`https://trekmail.net/mcp`, OAuth)	OAuth 2.1 com grupos legados ou âmbitos granulares	Direitos atuais, associação, âmbitos consentidos, conjuntos de ferramentas selecionados e suporte do transporte.	Política de segurança alojada	O subconjunto permitido por todos os limites ativos
MCP stdio autoalojado (`@trekmail/mcp-server`, local)	Um token `tm_live_` e, quando necessário, um token `tm_msg_`	Âmbitos do token, conjuntos de ferramentas selecionados, modo só de leitura e definições de segurança do operador. As ferramentas não autorizadas não são registadas.	Configuração do operador	O subconjunto permitido pelo token e pela configuração local
API REST diretamente	Um bearer token `tm_live_` ou `tm_msg_`	Âmbitos granulares do token, como `smtp:read`, `smtp:write` e `domains:delete`	Não aplicável	Os endpoints permitidos pelos âmbitos do token

Em resumo: o MCP HTTP alojado filtra as ferramentas anunciadas a partir da credencial OAuth; o MCP stdio combina os âmbitos do token com os conjuntos de ferramentas, o modo só de leitura e os controlos de segurança locais; a API REST é controlada diretamente pelos âmbitos granulares presentes no token. A autorização da API em tempo de execução continua a ser decisiva em todos os modos.

Referência de âmbitos

Conta e faturação

Âmbito	O que permite	Planos
`account:read`	Ver informações, plano, limites e utilização da conta	Starter · Pro · Agency
`billing:read`	Ver estado de faturação e histórico de faturas	Starter · Pro · Agency
`billing:autopay`	Pagar compras em seu nome sem pedir autorização em cada ocasião	Todos os planos, incluindo Nano

billing:autopay é o único âmbito que movimenta dinheiro, pelo que merece ser lido duas vezes.

Está deliberadamente separado de billing:read: uma ligação autorizada a ver a sua fatura não deve poder aumentá-la, e conceder leitura da faturação não é consentimento para gastar. Nunca é incluído automaticamente, um token ou ligação só o possui se o tiver concedido explicitamente, e está ausente de todos os grupos de âmbitos amplos antigos, portanto uma ligação autorizada antes da sua existência não pode gastar nada.

O que permite: comprar créditos de verificação de e-mail e iniciar uma subscrição. O que não permite, em circunstância alguma: cancelar, baixar ou alterar uma subscrição existente. Não existem endpoints para isso. Os gastos também são limitados por compra, por dia e por mês para toda a conta, independentemente do número de ligações que tenham o âmbito.

Está disponível em todos os planos porque os créditos de verificação são vendidos em todos eles, incluindo Nano.

Domínios

Âmbito	O que permite	Planos
`domains:read`	Listar domínios e ler detalhes, métricas de spam, endereços de reencaminhamento e estado dos aliases de domínio	Starter · Pro · Agency
`domains:create`	Adicionar novos domínios à conta	Pro · Agency
`domains:write`	Atualizar aliases de domínio, catch-all, DKIM, notas, endereços de reencaminhamento e definir se o domínio aloja correio recebido ou apenas envia	Pro · Agency
`domains:delete`	Eliminar domínios (perigoso)	Pro · Agency
`domains:dns:read`	Ver requisitos de DNS e resultados das verificações	Starter · Pro · Agency
`domains:dns:recheck`	Iniciar uma nova verificação de DNS	Pro · Agency

A entrega por alias de domínio está disponível a partir do Starter. Os tokens Starter podem ler o estado guardado e atual; ligar, alterar ou remover através da API/MCP exige a capacidade domains:write do Pro/Agency. As alterações no painel continuam disponíveis no Starter. Consulte Aliases de domínio através da API e MCP.

White Label

Estes âmbitos de tokens de operações só aparecem enquanto estiver ativo um período experimental ou add-on White Label pago. Durante o período de tolerância após o cancelamento, o proprietário mantém os âmbitos de leitura; os membros delegados e todos os âmbitos de escrita são removidos.

Âmbito	O que permite	Disponibilidade
`branding:read`	Ler marcas, recursos, hosts, estado da zona de correio e registos DNS necessários	Direito ativo; proprietário durante o período de tolerância
`branding:write`	Configurar marca, carregar ou remover recursos, criar pré-visualizações e verificar DNS	Direito ativo
`members:read`	Ler o catálogo de acesso e clientes ou membros de equipa White Label	Direito ativo; proprietário durante o período de tolerância
`members:write`	Convidar, atualizar, suspender, retomar, remover ou restaurar membros	Direito ativo
`activity:read`	Ler atividade White Label da conta e por membro	Direito ativo; proprietário durante o período de tolerância

A associação atual aplica outro limite. Um cliente ou colega de equipa nunca pode ampliar a própria função, acesso a domínios ou permissões personalizadas criando um token mais abrangente. Consulte Gerir equipas White Label com a API e MCP.

Caixas de correio

Âmbito	O que permite	Planos
`mailboxes:read`	Listar/ver caixas de correio e obter detalhes de configuração de clientes sem palavra-passe	Starter · Pro · Agency
`mailboxes:create`	Criar novas caixas de correio	Pro · Agency
`mailboxes:delete`	Eliminar caixas de correio (através de intenções de eliminação)	Pro · Agency
`mailboxes:invites:create`	Enviar convites de configuração de caixas	Pro · Agency
`mailboxes:forwarding:read`	Ver a configuração de reencaminhamento	Starter · Pro · Agency
`mailboxes:write`	Alterar palavra-passe, atualizar notas, pausar/retomar, suspender/restaurar início de sessão, definir acesso ao Drive	Pro · Agency
`mailboxes:forwarding:write`	Criar e modificar regras de reencaminhamento	Pro · Agency
`mailboxes:rules:read`	Ver filtros de correio	Starter · Pro · Agency
`mailboxes:rules:write`	Criar, atualizar e eliminar filtros de correio	Pro · Agency
`mailboxes:auto-reply:read`	Ver definições de resposta automática	Starter · Pro · Agency
`mailboxes:auto-reply:write`	Atualizar definições de resposta automática	Pro · Agency
`mailboxes:message-tokens:manage`	Criar, listar e revogar tokens de mensagens	Pro · Agency

Mensagens (token de mensagens)

Âmbito	O que permite	Planos
`messages:read`	Acesso de leitura a toda a interface de webmail: listar/ler mensagens e pastas, transferir anexos, obter a origem bruta, listar mensagens agendadas e contactos, exportar contactos, listar eventos, obter dados de resposta/reencaminhamento, listar identidades e rotas Enviar como de caixas ligadas, listar modelos e remetentes bloqueados	Pro · Agency
`messages:write`	Acesso de escrita: atualizar indicadores, eliminar/mover mensagens, denunciar spam/ham, ações em massa, criar/renomear/eliminar pastas, esvaziar Lixo/Spam, guardar/atualizar rascunhos, cancelar mensagens agendadas, gerir contactos, eventos, grupos, membros, identidades, política do remetente de resposta, modelos e remetentes bloqueados	Pro · Agency
`messages:send`	Enviar correio da caixa ou de uma identidade Enviar como autorizada e vinculada à origem; também permite agendar novas mensagens e cancelar envios agendados	Pro · Agency

Os âmbitos de mensagens são transportados por tokens de mensagens (prefixo tm_msg_), não por tokens de operações (prefixo tm_live_). Os tokens de mensagens são criados através da API usando um token de operações com o âmbito mailboxes:message-tokens:manage. Têm proteções específicas da API, além dos limites normais da rota de envio: por predefinição, as leituras permitem 30 pedidos por minuto e 5,000 leituras bem-sucedidas por dia por token; o envio permite 60 pedidos por minuto por token e 100 envios pela API por dia em toda a caixa. Um segundo contador de segurança do token tem como predefinição 500 envios por dia, pelo que o limite inferior da caixa geralmente prevalece.

Todos os novos endpoints da API de webmail (contactos, calendário, identidades, modelos, remetentes bloqueados, rascunhos, envios agendados, pastas, anexos) correspondem aos três âmbitos de mensagens existentes; não foram adicionados novos âmbitos. Os tokens atuais continuam a funcionar sem alterações.

messages:read não concede acesso de escrita. No OAuth alojado, aprovar a capacidade mais ampla messages:send provisiona em conjunto acesso de leitura, escrita e envio; um token tm_msg_ criado manualmente mantém exatamente os âmbitos escolhidos na criação.

Pedidos de suporte

Âmbito	O que permite	Planos
`tickets:read`	Listar e ver pedidos de suporte e mensagens	Starter · Pro · Agency
`tickets:write`	Criar pedidos, responder e fechar pedidos	Pro · Agency

Starter: só de leitura através da API. Abra e responda a pedidos no painel.

Configuração SMTP

Âmbito	O que permite	Planos
`smtp:read`	Ver a rota SMTP de um domínio, listar perfis guardados e a utilização exata por domínio/Enviar como, ler a predefinição da conta e consultar tarefas de teste	Starter · Pro · Agency
`smtp:write`	Definir a rota de um domínio, criar/atualizar/eliminar perfis, definir a predefinição da conta e executar testes de ligação	Pro · Agency

O SMTP é configurado por domínio (/api/v1/domains/{id}/smtp), com uma única predefinição para toda a conta (/api/v1/smtp/default) a decidir como começam os novos domínios. Consulte Visão geral da API para ver a lista completa de endpoints. Os endpoints legados ao nível da conta /api/v1/smtp continuam a responder por compatibilidade, mas já não controlam o encaminhamento.

Migrações

Âmbito	O que permite	Planos
`migrations:read`	Listar e ver detalhes das migrações	Starter · Pro · Agency
`migrations:write`	Iniciar, cancelar, repetir e eliminar migrações	Pro · Agency

Os âmbitos de migração são transportados por tokens de operações (prefixo tm_live_). O Starter pode ver migrações através da API e executá-las no painel. Pro e Agency também podem iniciar, cancelar, repetir e eliminar migrações através da API e MCP.

Cloudflare

Âmbito	O que permite	Planos
`cloudflare:read`	Validar tokens, listar zonas, pré-visualizar alterações de DNS	Starter · Pro · Agency
`cloudflare:write`	Ligar domínios e aplicar alterações de DNS através do Cloudflare	Pro · Agency
`cloudflare:delete`	Eliminar tokens Cloudflare (perigoso)	Pro · Agency

Drive

Âmbito	O que permite	Planos
`drive:account:read`	Navegar no Drive da conta, ver pastas/ficheiros/lixo/metadados de ligações de partilha e pedir URLs de transferência	Planos pagos ou add-on Drive ativo
`drive:account:write`	Carregar, criar pastas, mudar nomes, mover, enviar para o lixo e restaurar itens do Drive da conta	Planos pagos ou add-on Drive ativo
`drive:account:share`	Criar, listar e revogar ligações públicas para ficheiros do Drive da conta	Planos pagos ou add-on Drive ativo
`drive:account:purge`	Eliminar definitivamente ficheiros/pastas no lixo do Drive da conta e esvaziar o lixo	Planos pagos ou add-on Drive ativo; alto risco
`drive:mailbox:read`	Navegar nos espaços Drive de caixas permitidas	Planos pagos ou add-on Drive ativo
`drive:mailbox:write`	Carregar e alterar ficheiros/pastas nos espaços Drive de caixas permitidas	Planos pagos ou add-on Drive ativo
`drive:mailbox:share`	Criar, listar e revogar ligações públicas para ficheiros Drive de caixas permitidas	Planos pagos ou add-on Drive ativo
`drive:mailbox:purge`	Eliminar definitivamente itens no lixo do Drive de caixas	Planos pagos ou add-on Drive ativo; alto risco
`drive:addon:read`	Ler estado, preços e pré-visualização do cancelamento do add-on de armazenamento Drive	Nano · Starter · Pro · Agency quando existe contexto de add-on/Drive
`drive:devices:read`	Listar palavras-passe de dispositivos de sincronização sem expor os valores em texto simples	Planos pagos ou add-on Drive ativo
`drive:devices:write`	Criar, rodar e revogar palavras-passe de dispositivos de sincronização	Planos pagos ou add-on Drive ativo

Os âmbitos Drive pertencem a tokens de operações. Um token pode ser limitado a caixas selecionadas, e o Drive ocultará desse token os outros espaços de caixas. A compra, o redimensionamento e o cancelamento do add-on Drive não são operações de escrita da API/MCP; as alterações de faturação permanecem no painel.

Nano + add-on Drive: com um add-on de armazenamento Drive ativo, o Nano obtém o conjunto completo de âmbitos Drive. Nada mais é desbloqueado: apenas o Drive e os âmbitos do Verificador de e-mail que o Nano já possui. Se cancelar o add-on, os âmbitos de leitura continuam ativos durante o período de tolerância de 7 dias para que possa terminar as transferências ou a migração; a escrita, a partilha e a purga são interrompidas imediatamente.

Verificador de e-mail

Âmbito	O que permite	Planos
`verify:read`	Consultar créditos, listar tarefas, ver estado e resultados	Nano · Starter · Pro · Agency
`verify:write`	Enviar verificações, cancelar e eliminar tarefas (também concede acesso de leitura)	Nano · Starter · Pro · Agency

Os âmbitos do Verificador de e-mail estão disponíveis em todos os planos, incluindo Nano. A única limitação é o saldo de créditos. Consulte API do Verificador de e-mail para ver a referência completa dos endpoints.

Níveis de acesso dos planos

Plano	Acesso à API	Âmbitos disponíveis
Nano	Verificador de e-mail. Adicione um add-on de armazenamento Drive para obter toda a API Drive + MCP.	`verify:read`, `verify:write`. Com o add-on Drive: todos os âmbitos `drive:*`.
Starter	Drive completo, Verificador de e-mail completo e só de leitura no restante. Execute as escritas do painel no próprio painel.	`account:read`, `billing:read`, `domains:read`, `domains:dns:read`, `mailboxes:read`, `mailboxes:forwarding:read`, `mailboxes:rules:read`, `mailboxes:auto-reply:read`, `migrations:read`, `tickets:read`, `smtp:read`, `cloudflare:read`, `verify:read`, `verify:write`, todos os âmbitos `drive:*`.
Pro	Acesso completo	Todos os âmbitos de operações + âmbitos Drive + âmbitos de mensagens + âmbitos de migração + pedidos + SMTP + Cloudflare + conta + faturação + verificador
Agency	Acesso completo	Todos os âmbitos de operações + âmbitos Drive + âmbitos de mensagens + âmbitos de migração + pedidos + SMTP + Cloudflare + conta + faturação + verificador

Os âmbitos White Label são adicionais e não fazem parte do plano base Pro ou Agency. Só aparecem para essas contas enquanto o direito White Label estiver ativo.

O que acontece ao baixar o plano

Se baixar de Pro para Starter, os tokens existentes com âmbitos de escrita não são eliminados. Em vez disso, a API bloqueia em tempo de execução os pedidos que usam âmbitos não permitidos.

Por exemplo, um token com mailboxes:create num plano Starter receberá 403 com o código token_scope_blocked_by_plan ao tentar criar uma caixa. Os âmbitos de leitura do mesmo token continuarão a funcionar.

Para corrigir, revogue o token antigo e crie um novo apenas com os âmbitos permitidos pelo plano atual.

Âmbitos perigosos

Os âmbitos mailboxes:delete, domains:delete, migrations:write e cloudflare:delete são assinalados como perigosos no painel. Os tokens com estes âmbitos podem iniciar a eliminação de caixas ou domínios, remover tokens Cloudflare ou executar outras ações irreversíveis. Avalie se o seu caso de utilização realmente precisa deles.

Num servidor MCP alojado localmente, o administrador pode exigir TREKMAIL_ALLOW_DESTRUCTIVE=true antes de disponibilizar as ferramentas de eliminação. O MCP alojado usa os âmbitos aprovados durante o OAuth.

O âmbito messages:send permite enviar e-mails reais a partir da caixa. Num servidor MCP alojado localmente, o envio também pode exigir TREKMAIL_ALLOW_SENDING=true e confirm_send=true em cada chamada. Consulte Proteções de segurança e intenções de eliminação para obter detalhes.

O âmbito migrations:write permite iniciar migrações de e-mail que se ligam a servidores IMAP externos usando credenciais guardadas. Num servidor MCP alojado localmente, as escritas de migração também podem exigir TREKMAIL_ALLOW_MIGRATION=true e parâmetros de confirmação por chamada (confirm_start, confirm_cancel, confirm_retry).

Restrições de domínio

Os âmbitos controlam o que um token pode fazer. As restrições de domínio controlam onde pode fazê-lo.

Um token limitado a domínios específicos só verá e modificará recursos dentro desses domínios. Isto é útil para conceder a um prestador ou agente acesso ao domínio de um único cliente sem expor os restantes.

As verificações de âmbito ocorrem antes das verificações de restrição de domínio. Se um token não tiver o âmbito necessário, o pedido falha com 403, independentemente das restrições de domínio.

Soluções rápidas

403 "insufficient_scope": o token não possui o âmbito exigido por este endpoint. Crie um novo token com os âmbitos corretos.
403 "token_scope_blocked_by_plan": o plano deixou de permitir um ou mais âmbitos do token. Atualize o plano ou revogue o token e crie um novo com âmbitos permitidos.
403 "scope_blocked_by_entitlement": White Label está inativo ou foi tentada uma escrita durante o período de tolerância do cancelamento. Reative-o antes de voltar a autorizar a ligação.
403 "scope_blocked_by_membership": a função do membro atual ou a permissão personalizada não permite a ação. Peça ao proprietário da conta para alterar a associação.
Alguns âmbitos estão ocultos no formulário de criação: o plano não suporta esses âmbitos. Apenas são mostrados os âmbitos permitidos.