Autorizzazione e token

L'API pubblica si autorizza con token di accesso personali (PAT). Un singolo token è legato all'account e vale per tutte le tue entità del costruttore nei limiti degli ambiti concessi.

Creazione del token

Il token personale si crea nell'area personale, nella sezione dei token personali. Il valore del token viene mostrato una sola volta al momento della creazione — salvalo in un posto sicuro. Sul server il token è conservato solo in forma hash e non può essere recuperato; se lo perdi, emetti un nuovo token ed elimina quello vecchio.

Tutti i token personali iniziano con il prefisso mbp_.

Invio del token

Il token va passato in ogni richiesta tramite l'intestazione HTTP Authorization con lo schema Bearer:

Authorization: Bearer mbp_IL_TUO_TOKEN

La stessa intestazione viene usata anche per l'accesso dalla sessione web (lì si tratta di un JWT a breve vita), ma per le integrazioni usa sempre il token personale mbp_….

Ambiti di accesso (scopes)

Il token ha un insieme di ambiti nel formato risorsa:azione. La lettura richiede il suffisso :read, le modifiche :write. Ambiti disponibili:

  • bots:read, bots:write — bot, impostazioni, sincronizzazione, token del bot.
  • reactions:read, reactions:write — reazioni, import, test di formule, link, ordine.
  • labels:read, labels:write — etichette degli iscritti.
  • collections:read, collections:write — raccolte e record.
  • flows:read, flows:write — scenari.
  • integrations:read, integrations:write — integrazioni, connessioni, credenziali.
  • media:write — caricamento nella libreria media.
  • templates:read, templates:write — template dei bot.
  • settings:read, settings:write — impostazioni.
  • subscribers:read — iscritti e cronologia del dialogo (sola lettura).
  • broadcasts:write — trasmissioni e gestione.
  • stats:read — statistiche e analisi.
  • billing:read — saldo e piani (sola lettura).

L'ambito speciale * concede accesso completo all'intero set pubblico di endpoint.

Cosa è accessibile con il token e cosa no

Con il token personale sono accessibili solo gli endpoint del costruttore — quelli che «aiutano a costruire il bot». Non accessibili tramite PAT (solo dalla sessione web): login e registrazione, endpoint mobile, pagamento e ricarica del saldo, notifiche, log di audit, invio di messaggi dall'operatore nel dialogo, webhook in entrata e callback di pagamento, WebSocket. Una richiesta con token mbp_ verso queste route restituirà 401 o 403.

Se al token manca l'ambito necessario per una determinata route, verrà restituito 403. Per maggiori dettagli sui codici — vedi la guida agli errori.

Passo successivo

  • Avvio rapido API — prima richiesta con il token.
  • Errori — cosa significano 401 e 403.
  • MCP — stesso token per l'interfaccia agentiva.