> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.userbot.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.userbot.ai/_mcp/server. # Autenticazione Tutte le richieste alle API REST richiedono autenticazione tramite un **Access Token** Bearer. Il token identifica il partner che sta chiamando e autorizza l'accesso alle API associate all'account. L'header da includere in ogni chiamata è: ```http Authorization: Bearer ``` L'Access Token si genera in autonomia dalla dashboard Userbot. Non ha scadenza obbligatoria (puoi impostarla opzionalmente), ma va trattato come una password: chi lo possiede può inviare messaggi e accedere alle conversazioni associate all'account. Tratta l'Access Token come una password: non esporlo in client-side (browser, app mobile) né in repository di codice. Memorizzalo in un secret manager o variabili d'ambiente lato server. ## Ottenere un Access Token La procedura richiede pochi minuti e si fa interamente dalla dashboard, senza coinvolgere il supporto (salvo che la tab non sia visibile — vedi nota sotto). Per creare un nuovo Access Token Bearer: 1. Accedi alla dashboard su [my.userbot.ai](https://my.userbot.ai) 2. Clicca sul tuo profilo (menu utente in alto a destra) 3. Apri **Impostazioni account** 4. Seleziona la tab **Access Token** 5. Clicca per creare un nuovo token 6. Inserisci un **nome descrittivo** (es. "Integrazione CRM produzione", "Staging webhook test") — ti aiuterà a identificarlo in futuro 7. Scegli una **data di scadenza** oppure **Nessuna scadenza** se il token è per un'integrazione server-to-server stabile 8. Conferma con **Create token** Modal per creare un nuovo Access Token con campo nome e scadenza 9. **Copia la chiave generata** e conservala subito in un secret manager — **non verrà più mostrata** dopo la chiusura del modal Modal con la chiave generata e pulsante per confermare il salvataggio Per motivi di sicurezza la chiave è mostrata **una sola volta**. Dopo aver cliccato "I have saved the key" o chiuso il modal non sarà più possibile recuperarla: dovrai crearne uno nuovo e aggiornare le integrazioni che lo usavano. Se la tab **Access Token** non è visibile nelle impostazioni account, contatta il tuo **referente Userbot** per l'abilitazione API. L'accesso alle API potrebbe richiedere un piano o un'attivazione manuale. ## Secret Key dell'agente Oltre all'Access Token, le chiamate REST che inviano messaggi richiedono la **Secret Key** dell'Agente AI da integrare. In dashboard la trovi in **Integrazioni → API Keys**. Nelle richieste API la Secret Key compare come parametro di path `bot_key` — ad esempio `POST /v1/bots/{bot_key}/messages/`. Copia il valore dalla dashboard e sostituiscilo nel path al posto del placeholder `YOUR_BOT_KEY` negli esempi di questa documentazione. La Secret Key identifica quale agente deve gestire la conversazione. Trattala come credenziale sensibile: conservala lato server insieme all'Access Token, non in client-side né in repository pubblici. ## Esempio Una chiamata tipica con Access Token, Secret Key e consegna risposte via webhook: ```bash curl -X POST https://api.userbot.ai/v1/bots/YOUR_BOT_KEY/messages/ \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Ciao", "webhookOnly": true }' ``` La risposta REST restituisce ack e `session` ID. Le risposte dell'agente arrivano come eventi `message.added` sul webhook registrato in dashboard — vedi [Ricevere eventi webhook](/api-ricevere-eventi-webhook). Se il token non è valido, vedi la sezione errori sotto. ## Errori di autenticazione | Status | Causa | Cosa fare | | ------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | 401 | Token mancante, scaduto o non valido | Verifica che l'header `Authorization` sia presente e corretto; rigenera il token se scaduto | | 403 | Token valido ma operazione non consentita per l'account | Contatta il tuo referente Userbot per verificare l'accesso alle API | Per la tabella completa degli status HTTP e altri errori comuni, vedi [Codici di errore](/api-codici-errore).