Permissões e escopos

Cada pedido passa por três filtros, nesta ordem, e basta um dizer não:

1. 1A organização: a API e o MCP habilitados no seu workspace (se não, 403 platform_not_enabled), uma assinatura paga ativa (no teste grátis, 403 platform_requires_paid_plan) e em dia (402 payment_required), e o módulo ativo. Se o MB Suite não os abriu para essa organização ou essa pessoa, 403 platform_disabled.
2. 2A pessoa por trás da credencial: o papel, as permissões no módulo, a matriz de permissões do CRM e, se for um Vendedor com escopo, só o que é dele. Uma API key nunca pode mais do que a sua pessoa (403 crm_action_denied, com a ação em param).
3. 3A credencial: os escopos que você deu (403 scope_insufficient), a exclusão (403 delete_not_allowed) e as Contas que alcança (404 organization_not_found).

Escopos por módulo

A referência diz em cada operação o escopo que pede, a permissão do módulo, a ação do CRM e os papéis quando se aplicam. GET /v1/me e GET /v1/catalog devolvem só o que a sua credencial pode executar.

O irreversível

Toda operação que exclui é irreversible. Além da permissão de exclusão, fora da tela pede uma confirmação: dry_run → confirm_token (veja Prévia e confirmação). A maior parte do que é excluído do MB Suite fica 30 dias na lixeira (cada operação diz se dá para desfazer): a resposta traz o seu trash_item_id, e o item é restaurado com POST /v1/trash/{item_id}/restore (owner ou admin, com escrita no módulo do registro); pelo MCP, platform.trash.restore também o encontra por entity_type + entity_id.

E-mail e calendário conectados

O conteúdo das caixas e calendários conectados (Gmail, Google Calendar, Outlook) não sai por padrão. Ele abre com três travas, todas desativadas no começo:

1. 1A organização: um owner ativa em Configurações → API e MCP → API keys, «E-mail e calendário conectados». Desligado, essas operações não existem para nenhuma credencial (404).
2. 2A credencial: a API key ou o app tem que ter a permissão (na API key, o bloco «E-mail e calendário conectados»; no OAuth, connected_content:read, que a pessoa marca ao autorizar). Sem ela, 403 connected_content_not_granted.
3. 3O dado: mesmo com as duas, uma credencial vê só a caixa e o calendário da pessoa que a criou ou autorizou, e só as conversas e eventos vinculados a pessoas, empresas ou negócios do CRM. Nunca a caixa inteira nem a de outra pessoa.

As operações afetadas levam a marca «E-mail e calendário conectados» na referência. As condições de uso desse conteúdo estão na seção 4a dos Termos.

Plataformas com termos próprios

Os termos de algumas plataformas conectadas limitam o que se pode fazer com os seus dados e as suas APIs pela API e pelo MCP do MB Suite. Na tela do MB Suite funcionam como sempre. Isso pode mudar se uma plataforma autorizar outro uso.

• Google Ads, Google Business Profile, TikTok e YouTube: os dados e as alterações não estão disponíveis pela API nem pelo MCP.
• LinkedIn: dos seus dados, só os relatórios das contas de anúncios e das páginas (estrutura, desempenho e as próprias publicações) e as respostas dos formulários de Lead Gen, e só com uma API key da organização pela API REST, não pelo MCP nem por um app conectado; os comentários, as menções e o restante do conteúdo dos seus membros não estão disponíveis, e publicar, responder ou alterar algo no LinkedIn também não.

Um pedido que não cumpre essas regras responde 403 platform_terms_restricted: details.platform diz qual e details.access, o que permite (none ou own_key). Pelo MCP, essas operações não aparecem. Os webhooks não enviam eventos que tragam dados dessas plataformas.

Permissões especiais de uma API key

Há três permissões que não são escopos: os owners e os admins as concedem, na API key, e elas vêm desligadas por padrão. Para qualquer outra credencial (uma API key sem a permissão, um app OAuth e, no caso do Cofre, a API key usada pelo MCP) vault.items.reveal_secret, ai.agents.update_live e ai.agents.create_with_key não existem (404).

• Revelar senhas do Cofre: a API key pede a senha das credenciais escolhidas na API key (até 50, do Cofre da sua organização) com vault.items.reveal_secret, só por REST. Também precisa do escopo vault:read. O limite é de 30 por hora para a pessoa por trás da API key, somando todas as API keys dela. Essa pessoa precisa poder usar cada credencial. Cada revelação fica registrada na Atividade da credencial, assim como cada pedido de uma credencial fora da lista ou sem acesso.
• Editar agentes de IA ao vivo: com ai.agents.get a API key recebe as instruções e o conhecimento dos agentes, e com ai.agents.update_live edita qualquer um deles, inclusive os que atendem ao vivo na Equipe IA, sempre com dry_run e confirm_token.
• Criar agentes de IA: com ai.agents.create_with_key a API key cria agentes de IA na sua organização e nas Contas que alcança, inclusive versões próprias dos agentes do MB Suite, sempre com dry_run e confirm_token. Um agente novo não atende ninguém até alguém atribuí-lo a um cargo no MB Suite.

Uma API key de teste nunca as tem.

Agências e Contas

Uma API key de workspace alcança as Contas que você escolheu ao criá-la e que a pessoa vê; os webhooks de um workspace podem escutar as suas Contas. Uma API key de uma Conta trabalha só nessa Conta.