Autenticación y API keys

Todo pedido lleva Authorization: Bearer <credencial>. Hay dos credenciales y las dos actúan como una persona de la organización: nunca pueden más que ella.

API keys

• Dónde: Configuración → API y MCP → API keys (owners y admins). La API key se ve una sola vez; en la lista queda su prefijo para reconocerla.
• A quién representa: un miembro de la organización (tú, por defecto). Nadie puede crear una API key a nombre de alguien con un rol más alto que el suyo.
• Permisos: por módulo, Lectura o Lectura y escritura; Permitir eliminar va aparte y viene apagado. Ver Permisos y alcances.
• Vencimiento: nunca, o 30, 90, 365 días.
• Rotar genera una API key nueva con los mismos permisos; la anterior sigue funcionando 24 horas para que cambies la integración sin cortes.
• Suspender, reactivar y revocar desde la misma pestaña. Si la persona a la que representa deja la organización, la API key queda suspendida sola.
• Tope: la cantidad de API keys activas depende del plan (ver Límites).

API keys de prueba: la organización de práctica

Una API key de prueba (mbs_test_ y 46 caracteres) trabaja solo sobre la organización de práctica de tu workspace: una organización aparte, con datos de ejemplo del CRM (un embudo con sus etapas, empresas, personas, tratos en distintas etapas y actividades) y algunas etiquetas de Actividad para probar el etiquetado de entradas (una práctica creada antes del 12-10-2026 las recibe al reiniciarla con platform.sandbox.reset), que nace sola con la primera API key de prueba. Sirve para armar y probar una integración sin tocar datos reales.

• Cómo se crea: en Configuración → API y MCP → API keys, Crear API key con el entorno Prueba (solo en un workspace). Actúa como un owner o admin del workspace y no alcanza Cuentas: MB-Organization y org_id no cambian nada, el pedido siempre va a la práctica.
• Nada sale de MB Suite: enviar un correo (crm.email.send) o un WhatsApp (crm.whatsapp.send_text, send_template, send_media) se simula: la copia queda en la práctica (la actividad del correo, el mensaje en su hilo) y la respuesta trae simulated: true (en la API, también el encabezado MB-Simulated: true). Exportar un PDF también se simula: no se dibuja nada y se guarda un PDF de una página que lo dice (dashboards.dashboards.export_pdf devuelve el enlace; reports.instances.export_pdf responde queued y el enlace sale de reports.instances.pdf_url). Lo demás que toca otra plataforma responde 409 sandbox_external_unavailable. GET /v1/me y mb_context dicen en practice qué se simula.
• Cupo propio: la práctica tiene sus límites, los de la fila Práctica de Límites, y nunca gasta el cupo de tu workspace.
• Webhooks de prueba: en la pestaña Webhooks, el entorno Prueba crea suscripciones en la práctica. Reciben solo lo que hacen las API keys de prueba y se entregan de verdad, firmadas igual; ninguna suscripción de producción recibe eventos de la práctica.
• Reiniciar datos de prueba: desde la tarjeta Organización de práctica de la pestaña API keys, o con POST /v1/sandbox/reset (primero con dry_run). Borra todo lo que acumuló la práctica y vuelve a sembrar los datos de ejemplo; las API keys y las suscripciones de prueba se mantienen. GET /v1/sandbox dice su estado.

curl https://api.mb-suite.com/v1/crm/deals?limit=5 \
  -H "Authorization: Bearer $MB_TEST_KEY"

Workspaces y Cuentas: MB-Organization

Una API key de workspace puede trabajar en sus Cuentas si al crearla elegiste Acceder también a las Cuentas (todas o algunas, y siempre solo las que ve la persona). Para apuntar un pedido a una Cuenta, manda su id en el encabezado MB-Organization (o org_id en la query o el cuerpo). Sin él, el pedido va a la organización de la API key.

curl https://api.mb-suite.com/v1/crm/deals \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "MB-Organization: ACCOUNT_ID"

Una organización que la API key no alcanza responde 404 organization_not_found: nunca decimos si existe. Una Cuenta también puede tener API keys propias si paga su propia suscripción o si su agencia se lo permite (Partners → Ver permisos).

OAuth 2.1 para apps

Una app que actúa por una persona usa el flujo authorization_code con PKCE (S256, obligatorio). Los clientes son públicos, sin secreto. Todo lo que necesitas está en el documento de descubrimiento: https://mb-suite.com/.well-known/oauth-authorization-server.

• Registro: dinámico (RFC 7591) en https://mb-suite.com/api/platform/oauth/register, con redirect_uris https:// o de loopback con puerto; o un client_id que sea la URL de tu documento de metadata.
• Autorizar: lleva a la persona a https://mb-suite.com/oauth/authorize con resource (obligatorio, RFC 8707): https://api.mb-suite.com para la API o https://mcp.mb-suite.com para el MCP. Un token sirve solo para el recurso que pediste.
• Consentimiento: la persona elige la organización y revisa los permisos (escribir y borrar vienen apagados), las Cuentas y, si la organización lo permite, correo y calendario conectados.
• Tokens: el de acceso (mbo_…) dura 1 hora; el de renovación (mbr_…), 30 días, y se usa una sola vez: cada renovación devuelve uno nuevo y reusar uno viejo revoca toda la autorización. Ninguna autorización dura más de 365 días.
• Revocar: https://mb-suite.com/api/platform/oauth/revoke (RFC 7009), o la persona desde Configuración → API y MCP → MCP, con «Desconectar». Corta al instante.

GET https://mb-suite.com/oauth/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https://app.example.com/callback
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.mb-suite.com
  &scope=crm:write
  &state=RANDOM_STATE

Alcances

scope usa los mismos permisos que las API keys: <módulo>:read, <módulo>:write y <módulo>:delete (el interruptor de borrado), más connected_content:read para correo y calendario conectados. Sin scope, la app pide solo lectura de los módulos con operaciones. Escribir lo decide siempre la persona en el consentimiento, también cuando la app lo pide con scope: «Lectura y escritura» es un interruptor apagado por defecto (con scope, cubre solo los módulos donde la app pidió :write), y Miembros, Branding, Cuentas, Client Portal, Email Marketing e Integraciones tienen cada uno el suyo. Borrar es aparte, y developer_platform (crear webhooks) se pide explícito. Pide solo lo que tu integración usa: lo que la persona no activa no viene en el token, y el scope de la respuesta de /token dice lo concedido.