Autenticação e API keys

Todo pedido leva Authorization: Bearer <credencial>. Há dois tipos de credencial e os dois agem como uma pessoa da organização: nunca podem mais do que ela.

API keys

• Onde: Configurações → API e MCP → API keys (owners e admins). A API key aparece uma única vez; na lista fica o prefixo para reconhecê-la.
• Quem ela representa: um membro da organização (você, por padrão). Ninguém pode criar uma API key em nome de alguém com um papel mais alto que o seu.
• Permissões: por módulo, Leitura ou Leitura e escrita; Permitir exclusões é à parte e vem desligado. Veja Permissões e escopos.
• Vencimento: nunca, ou 30, 90, 365 dias.
• Rotacionar gera uma API key nova com as mesmas permissões; a anterior continua funcionando por 24 horas para você trocar a integração sem cortes.
• Suspender, reativar e revogar na mesma aba. Se a pessoa que ela representa sair da organização, a API key fica suspensa sozinha.
• Limite: a quantidade de API keys ativas depende do plano (veja Limites).

API keys de teste: a organização de prática

Uma API key de teste (mbs_test_ e 46 caracteres) trabalha só na organização de prática do seu workspace: uma organização à parte, com dados de exemplo do CRM (um funil com as etapas, empresas, pessoas, negócios em etapas diferentes e atividades) e algumas etiquetas de Atividade para testar a etiquetagem de entradas (uma prática criada antes de 12-10-2026 as recebe ao ser reiniciada com platform.sandbox.reset), que nasce sozinha com a primeira API key de teste. Serve para montar e testar uma integração sem tocar dados reais.

• Como criar: em Configurações → API e MCP → API keys, Criar API key com o ambiente Teste (só num workspace). Ela age como um owner ou admin do workspace e não alcança Contas: MB-Organization e org_id não mudam nada, o pedido sempre vai para a prática.
• Nada sai do MB Suite: enviar um e-mail (crm.email.send) ou um WhatsApp (crm.whatsapp.send_text, send_template, send_media) é simulado: a cópia fica na prática (a atividade do e-mail, a mensagem na conversa) e a resposta traz simulated: true (na API, também o cabeçalho MB-Simulated: true). Exportar um PDF também é simulado: nada é desenhado e fica salvo um PDF de uma página que diz isso (dashboards.dashboards.export_pdf devolve o link; reports.instances.export_pdf responde queued e o link sai de reports.instances.pdf_url). O resto que usa outra plataforma responde 409 sandbox_external_unavailable. GET /v1/me e mb_context dizem em practice o que é simulado.
• Cota própria: a prática tem os seus limites, os da linha Prática de Limites, e nunca gasta a cota do seu workspace.
• Webhooks de teste: na aba Webhooks, o ambiente Teste cria assinaturas na prática. Elas recebem só o que as API keys de teste fazem e são entregues de verdade, assinadas igual; nenhuma assinatura de produção recebe eventos da prática.
• Reiniciar dados de teste: no cartão Organização de prática da aba API keys, ou com POST /v1/sandbox/reset (primeiro com dry_run). Exclui tudo o que a prática acumulou e semeia de novo os dados de exemplo; as API keys e as assinaturas de teste são mantidas. GET /v1/sandbox diz o estado.

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

Workspaces e Contas: MB-Organization

Uma API key de workspace pode trabalhar nas suas Contas se, ao criá-la, você escolheu Acessar também as Contas (todas ou algumas, e sempre só as que a pessoa vê). Para apontar um pedido para uma Conta, envie o id dela no cabeçalho MB-Organization (ou org_id na query ou no corpo). Sem ele, o pedido vai para a organização da API key.

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

Uma organização que a API key não alcança responde 404 organization_not_found: nunca dizemos se existe. Uma Conta também pode ter API keys próprias se paga a sua própria assinatura ou se a agência permitir (Partners → Ver permissões).

OAuth 2.1 para apps

Um app que age por uma pessoa usa o fluxo authorization_code com PKCE (S256, obrigatório). Os clientes são públicos, sem segredo. Tudo o que você precisa está no documento de descoberta: https://mb-suite.com/.well-known/oauth-authorization-server.

• Registro: dinâmico (RFC 7591) em https://mb-suite.com/api/platform/oauth/register, com redirect_uris https:// ou de loopback com porta; ou um client_id que seja a URL do seu documento de metadata.
• Autorizar: leve a pessoa a https://mb-suite.com/oauth/authorize com resource (obrigatório, RFC 8707): https://api.mb-suite.com para a API ou https://mcp.mb-suite.com para o MCP. Um token só serve para o recurso que você pediu.
• Consentimento: a pessoa escolhe a organização e revisa as permissões (escrever e excluir vêm desligados), as Contas e, se a organização permitir, e-mail e calendário conectados.
• Tokens: o de acesso (mbo_…) dura 1 hora; o de renovação (mbr_…), 30 dias, e é de uso único: cada renovação devolve um novo e reutilizar um antigo revoga toda a autorização. Nenhuma autorização dura mais de 365 dias.
• Revogar: https://mb-suite.com/api/platform/oauth/revoke (RFC 7009), ou a pessoa em Configurações → API e MCP → MCP, com «Desconectar». Corta na hora.

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

Escopos

scope usa as mesmas permissões das API keys: <módulo>:read, <módulo>:write e <módulo>:delete (o interruptor de exclusão), mais connected_content:read para e-mail e calendário conectados. Sem scope, o app pede só leitura dos módulos com operações. Escrever é sempre decisão da pessoa no consentimento, mesmo quando o app pede com scope: «Leitura e escrita» é um interruptor desligado por padrão (com scope, só cobre os módulos em que o app pediu :write), e Membros, Branding, Contas, Client Portal, Email Marketing e Integrações têm cada um o seu. Excluir é à parte, e developer_platform (criar webhooks) é pedido explicitamente. Peça só o que a sua integração usa: o que a pessoa não ativa não vem no token, e o scope da resposta de /token diz o que foi concedido.