Permisos y alcances

Qué puede hacer cada credencial: la persona que representa, los alcances por módulo, el borrado, correo y calendario conectados, y los permisos especiales de una API key.

Cada pedido pasa por tres filtros, en este orden, y basta con que uno diga que no:

1La organización: la API y el MCP habilitados en su workspace (si no, 403 platform_not_enabled), una suscripción paga activa (en la prueba gratis, 403 platform_requires_paid_plan) y al día (402 payment_required), y el módulo activo. Si MB Suite no los abrió para esa organización o esa persona, 403 platform_disabled.
2La persona detrás de la credencial: su rol, sus permisos en el módulo, la matriz de permisos del CRM y, si es un Vendedor con alcance, solo lo suyo. Una API key nunca puede más que su persona (403 crm_action_denied, con la acción en param).
3La credencial: los alcances que le diste (403 scope_insufficient), el borrado (403 delete_not_allowed) y las Cuentas que alcanza (404 organization_not_found).

Alcances por módulo

Alcance	Qué permite
`<módulo>:read`	Las lecturas del módulo: los `GET` y las búsquedas.
`<módulo>:write`	Lecturas y escrituras. No incluye borrar.
«Permitir eliminar» · `<módulo>:delete`	Las operaciones irreversibles (borrar, purgar, fusionar), sobre los módulos con escritura. Apagado por defecto.

La referencia dice en cada operación el alcance que pide, el permiso del módulo, la acción del CRM y los roles cuando aplican. GET /v1/me y GET /v1/catalog devuelven solo lo que tu credencial puede correr.

Lo irreversible

Toda operación que borra es irreversible. Además del permiso de borrado, fuera de la pantalla pide una confirmación: dry_run → confirm_token (ver Vista previa y confirmación). La mayoría de lo que se borra de MB Suite queda 30 días en la papelera (cada operación dice si se puede deshacer): la respuesta trae su trash_item_id y se restaura con POST /v1/trash/{item_id}/restore (owner o admin, con escritura en el módulo del registro); por el MCP, platform.trash.restore también lo encuentra por entity_type + entity_id.

Correo y calendario conectados

El contenido de las casillas y los calendarios conectados (Gmail, Google Calendar, Outlook) no sale por defecto. Se abre con tres candados, todos desactivados al empezar:

1La organización: un owner lo activa en Configuración → API y MCP → API keys, «Correo y calendario conectados». Apagado, esas operaciones no existen para ninguna credencial (404).
2La credencial: la API key o la app tiene que traer el permiso (en la API key, el bloque «Correo y calendario conectados»; en OAuth, connected_content:read, que la persona tilda al autorizar). Sin él, 403 connected_content_not_granted.
3El dato: aun con los dos, una credencial ve solo la casilla y el calendario de la persona que la creó o la autorizó, y solo los hilos y eventos vinculados a personas, empresas o tratos del CRM. Nunca la casilla entera ni la de otra persona.

Las operaciones afectadas llevan la marca «Correo y calendario conectados» en la referencia. Las condiciones de uso de ese contenido están en la sección 4a de los Términos.

Plataformas con términos propios

Los términos de algunas plataformas conectadas limitan lo que se puede hacer con sus datos y sus APIs por la API y el MCP de MB Suite. En la pantalla de MB Suite funcionan como siempre. Esto puede cambiar si una plataforma autoriza otro uso.

Google Ads, Google Business Profile, TikTok y YouTube: sus datos y los cambios no están disponibles por la API ni por el MCP.
LinkedIn: de sus datos, solo los informes de las cuentas publicitarias y las páginas (estructura, rendimiento y sus propias publicaciones) y las respuestas de los formularios de Lead Gen, y solo con una API key de la organización por la API REST, no por el MCP ni por una app conectada; los comentarios, las menciones y el resto del contenido de sus miembros no están disponibles, y publicar, responder o cambiar algo en LinkedIn tampoco.

Un pedido que no cumple estas reglas responde 403 platform_terms_restricted: details.platform dice cuál y details.access, qué deja (none u own_key). Por el MCP, esas operaciones no aparecen. Los webhooks no envían eventos que traigan datos de estas plataformas.

Permisos especiales de una API key

Hay tres permisos que no son alcances: los dan los owners y los admins, en la API key, y están apagados por defecto. Para cualquier otra credencial (una API key sin el permiso, una app OAuth y, en el caso de la Bóveda, la API key usada por el MCP) vault.items.reveal_secret, ai.agents.update_live y ai.agents.create_with_key no existen (404).

Revelar contraseñas de la Bóveda: la API key pide la contraseña de las credenciales elegidas en la API key (hasta 50, de la Bóveda de su organización) con vault.items.reveal_secret, solo por REST. Necesita además el alcance vault:read. El tope es de 30 por hora para la persona detrás de la API key, sumando todas sus API keys. Esa persona tiene que poder usar cada credencial. Cada revelación queda registrada en la Actividad de la credencial, y también cada pedido de una credencial fuera de la lista o sin acceso.
Editar agentes de IA en vivo: con ai.agents.get la API key recibe las instrucciones y el conocimiento de los agentes, y con ai.agents.update_live edita cualquiera de ellos, incluidos los que atienden en vivo en el Equipo IA, siempre con dry_run y confirm_token.
Crear agentes de IA: con ai.agents.create_with_key la API key crea agentes de IA en su organización y en las Cuentas que alcanza, también versiones propias de los agentes de MB Suite, siempre con dry_run y confirm_token. Un agente nuevo no atiende a nadie hasta que alguien lo asigne a un puesto desde MB Suite.

Una API key de prueba no los lleva.

Agencias y Cuentas

Una API key de workspace alcanza las Cuentas que elegiste al crearla y que la persona ve; los webhooks de un workspace pueden escuchar a sus Cuentas. Una API key de una Cuenta trabaja solo en esa Cuenta.