> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.userbot.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server. # Autenticazione e chiavi Ogni chiamata all'API si autentica con una chiave, passata nell'header `Authorization`. Non ci sono altri metodi: niente cookie di sessione, niente OAuth, niente parametri nell'URL. ```bash curl https://api.userbot.ai/api/eu/v1/models \ -H "Authorization: Bearer $USERBOT_API_KEY" ``` Le chiavi iniziano sempre con `ub_`. Vanno usate solo da un server: una chiamata che arriva da un browser viene rifiutata con `403` prima ancora di controllare la chiave. ## Chiave personale o chiave dell'area di lavoro Esistono due tipi di chiave, e la differenza sta in chi paga e in chi la controlla. | | Chiave personale | Chiave dell'area di lavoro | | ----------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | Dove si crea | Voce **Sviluppatore** nella barra laterale | **Impostazioni › Funzionalità › Chiavi API** | | Chi la crea | Gli Admin, e gli Editor che hanno il permesso **Creare chiavi API personali** | Solo gli Admin | | Chi la vede e la revoca | Solo chi la possiede, nemmeno gli Admin | Tutti gli Admin | | Cosa può chiamare | Completamenti ed embedding | Quello che scegli in **Permessi**: **Completion**, **Embedding** o entrambi | | Chi paga | Chi la possiede: consuma il suo utilizzo, come la sua chat | L'area di lavoro, con il credito prepagato | Usa una chiave personale quando sviluppi o provi qualcosa per conto tuo. Usa una chiave dell'area di lavoro per un'integrazione dell'azienda che deve continuare a funzionare anche quando chi l'ha scritta cambia ruolo. Le chiavi dell'area di lavoro sono spiegate in [Chiavi API dell'area di lavoro](/chiavi-api-admin). ## La pagina Sviluppatore La voce **Sviluppatore** compare a chi è nell'elenco di **Accesso** delle **Chiavi API**, deciso dagli amministratori. Di partenza l'accesso è aperto a tutta l'area di lavoro; se non vedi la voce, l'hanno spenta o riservata ad altri. Vale anche per gli Admin: configurano la funzionalità, ma la voce la vedono solo se sono nell'elenco. La pagina si apre dalla voce **Sviluppatore** e ha il titolo **Chiavi API**, con **Crea chiave API** in alto a destra. ![La pagina Sviluppatore: la voce evidenziata nella barra laterale, il pulsante Crea chiave API evidenziato in alto a destra, le schede Le tue chiavi, Il tuo utilizzo e I modelli disponibili, l'elenco ancora vuoto e sotto gli esempi di codice](/_fern-img/b97f7f205c94b0c7c3e6e2d4c84867c19e602943cab89fd7203140fe948f5793.webp) Le schede sono tre: | Scheda | Cosa trovi | | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Le tue chiavi** | Le tue chiavi personali e, sotto, esempi di codice da copiare | | **Il tuo utilizzo** | Spesa, richieste e token delle tue chiavi, per fornitore, per modello e per chiave, confrontati con il tuo budget | | **I modelli disponibili** | I modelli che puoi chiamare, con l'id da mettere in `model` e il prezzo di listino | Un Membro vede la pagina ma non può creare chiavi, nemmeno se il permesso è acceso per il suo ruolo. Un Editor può crearle solo se un amministratore gli ha dato il permesso in **Ruoli**: di partenza ce l'hanno solo gli Admin. ## Creare una chiave personale #### Apri Sviluppatore e premi Crea chiave API Se il pulsante non c'è, il tuo ruolo non ha il permesso di creare chiavi: chiedilo a chi amministra l'area di lavoro. ![Il titolo Chiavi API con il pulsante Crea chiave API evidenziato a destra, e sotto le schede Le tue chiavi, Il tuo utilizzo e I modelli disponibili](/_fern-img/452cef82f7ac2bed150fb16aa36ac5908c95a6ad3fef26d5741226006b861d26.webp) #### Dai un nome che dica dove viene usata **Backend produzione**, **Job notturno fatture**, **Staging**: serve a capire cosa stai spegnendo il giorno che la revochi. Una chiave personale può chiamare sia i completamenti sia gli embedding, quindi non ci sono permessi da scegliere. ![La finestra Crea chiave API per una chiave personale: il nome Backend produzione, la nota che le chiavi personali chiamano completion ed embedding, la Whitelist IP vuota con l'avviso giallo, Annulla e Crea](/_fern-img/c0daf9e054c126b8af6ca1b439ef1489c7fd7283c03303de01142cd652da2d78.webp) #### Limita gli indirizzi, se puoi In **Whitelist IP (opzionale)** scrivi gli indirizzi o gli intervalli CIDR, IPv4 o IPv6, da cui partiranno le chiamate. Lasciato vuoto, chiunque abbia la chiave può usarla da qualsiasi rete. ![La Whitelist IP della finestra con un intervallo d'esempio già aggiunto e il campo per il successivo, che accetta anche IPv6](/_fern-img/041df4e83160988d0d9031339cb62eb5819238529326bfaacac1f76d97ee9eb5.webp) #### Copia la chiave adesso Il valore in chiaro compare una volta sola, subito dopo **Crea**. Copialo e mettilo nel gestore di segreti del tuo ambiente prima di chiudere la finestra. ![La finestra dopo Crea: chiave creata, l'avviso che non verrà più mostrata per intero, il valore sfocato e il pulsante Copia evidenziato](/_fern-img/453f7ea337174e4e0ab8dd556cd78cb4d8ac5972f8931db5e6eac0c9938cd9bd.webp) Dopo la creazione, nell'elenco resta una versione mascherata del tipo `ub_5f3a91…840a`, con le colonne **Permessi**, **IP**, **Creata** e **Ultimo uso**. Userbot conserva solo l'impronta crittografica della chiave: nessuno, supporto compreso, può rileggerla o rimandartela. Gli amministratori ricevono una notifica per ogni chiave creata, e la creazione finisce nel [Registro di audit](/audit). Se arriva una notifica per una chiave che nessuno aveva previsto, va revocata. ## Quando una chiave smette di funzionare Una chiave è legata alla persona che la possiede (per quelle personali) o all'Admin che l'ha creata (per quelle dell'area di lavoro). Smette di funzionare in questi casi: * **è stata revocata**, a mano o perché quella persona è stata rimossa dall'area di lavoro: la rimozione revoca tutte le sue chiavi, comprese quelle dell'area di lavoro che aveva creato; * **è scaduta**. La durata la decide l'amministratore in **Impostazioni › Sicurezza e controllo › Sicurezza e accesso**, voce **Scadenza predefinita chiavi API**: **Nessuna scadenza** oppure 1, 3, 6, 12 o 24 mesi, con 12 mesi di partenza. Vale per le chiavi create da quel momento; * **la persona non è più nell'elenco di Accesso** delle Chiavi API, o la funzionalità è stata spenta. In questo caso la chiave non è revocata: torna a funzionare se la persona rientra nell'elenco. Per i sistemi che devono restare accesi, quindi, una chiave personale è una scelta fragile: basta un cambio di gruppo per spegnerla. → [Sicurezza dell'area di lavoro](/sicurezza-workspace) ## Revocare una chiave Nell'elenco, apri il menu **⋯** sulla riga della chiave e scegli **Revoca**, poi conferma. Nello stesso menu, **Intervalli IP** cambia la whitelist senza rigenerare la chiave. > **Warning** > > La revoca ha effetto immediato e non si annulla. Ogni sistema che stava usando > quella chiave riceve `401` alla chiamata successiva, senza periodo di > tolleranza. Prepara la chiave nuova prima di revocare la vecchia. ## Gli errori di autenticazione Il corpo dell'errore contiene un campo `code` che distingue i casi. | Codice HTTP | `code` | Cosa è successo | | ----------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | `invalid_api_key` | Header mancante o malformato, oppure chiave inesistente | | `401` | `inactive_api_key` | La chiave è stata revocata o è scaduta | | `403` | `ip_not_allowed` | La chiamata arriva da un indirizzo fuori dalla whitelist della chiave | | `403` | `developer_permission_required` | Chi possiede la chiave non è più nell'elenco di **Accesso**, o le Chiavi API sono spente | | `403` | | La chiave non ha il permesso per quell'endpoint (per esempio una chiave solo **Embedding** su `/chat/completions`), la chiamata arriva da un browser, oppure l'area di lavoro ha le **Restrizioni di accesso IP** attive e il tuo server non è fra gli intervalli consentiti | Nessuno di questi errori si risolve riprovando: va sistemata la chiave o la configurazione. ## Buone pratiche **Una chiave per ambiente e per servizio.** Produzione, staging e il portatile di chi sviluppa non condividono la stessa chiave. Così, quando una va sostituita, spegni una cosa sola e sai quale. **Mai nel codice sorgente.** La chiave sta in una variabile d'ambiente o in un gestore di segreti. Una chiave finita in un repository va considerata compromessa anche se il repository è privato: la cronologia di git la conserva. **Mai lato client.** Una chiave dentro un'applicazione web, mobile o desktop è leggibile da chiunque abbia l'applicazione. Le chiamate partono dal tuo server. **Ruotale prima che scadano.** La rotazione senza interruzioni ha un ordine preciso. #### Crea la chiave nuova Con un nome che la distingua dalla vecchia. ![La finestra Crea chiave API con nel Nome della chiave lo stesso nome della vecchia più il mese, evidenziato](/_fern-img/ed8978b255879da69137e7e5b416171c6805cfca09053c21fd145a372b1d728a.webp) #### Sostituiscila nella configurazione Aggiorna il segreto e riavvia i servizi che lo leggono. #### Controlla l'ultimo uso Nell'elenco delle chiavi, verifica nella colonna **Ultimo uso** che la vecchia abbia smesso di ricevere chiamate. ![Le due chiavi in elenco: la nuova, usata oggi, e la vecchia, evidenziata, con l'ultimo uso fermo a giorni prima nella colonna Ultimo uso](/_fern-img/9346c50bfa4f142a228f81467f1be04e5a04ce1e9f1794e4d0d6579bcff6ff6a.webp) #### Revoca la vecchia Solo a quel punto. ![La conferma Revocare la chiave API? con il nome della chiave vecchia, l'avviso che l'azione non si annulla e Revoca evidenziato](/_fern-img/5ebef55477b41082e8654de3d4a2fb0fbbcf463dfee80384bc5f0c5438dc7783.webp) ## Se una chiave è esposta Revocala subito, poi crea la sostituta: in questo ordine, non nell'altro. Una chiave lasciata attiva "finché non sistemiamo" continua a spendere. Controlla poi in [Costi, budget e analytics](/api-costi) cosa è stato consumato mentre era in circolazione.