> 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.

# Chiavi API dell'area di lavoro

**Impostazioni › Funzionalità › Chiavi API** è il posto da cui un amministratore
governa l'uso programmatico di Userbot: chi può avere una chiave, quali chiavi
dell'area di lavoro esistono, quali modelli si possono chiamare e quanto si può
spendere. La pagina la vedono solo gli Admin, anche se un Editor ha il permesso
di gestire le impostazioni; chi apre l'indirizzo senza esserlo legge **Non hai
accesso ad API Keys in questa area di lavoro.**

Per come si usa l'API dal lato di chi sviluppa, vedi
[Introduzione all'API](/api).

La pagina ha quattro schede:

| Scheda             | A cosa serve                                                                   |
| ------------------ | ------------------------------------------------------------------------------ |
| **Area di lavoro** | Chi ha accesso, le chiavi dell'area di lavoro, i modelli richiamabili          |
| **Costo e budget** | Il credito, il tetto di spesa dell'area di lavoro, il budget di ogni membro    |
| **Analytics**      | Chi ha speso cosa, con quali modelli → [Costi, budget e analytics](/api-costi) |
| **Documentazione** | L'**ID area di lavoro** e gli esempi di codice per EU e Global                 |

![La pagina Chiavi API nella scheda Area di lavoro: le quattro schede in alto, il controllo Accesso con Tutta l'area di lavoro selezionato, l'elenco delle Chiavi API workspace con il pulsante Crea chiave API e l'inizio di Modelli API disponibili](/_fern-img/39b62904618817971b5b18e28dc354d3405298da533c791ec226e50d6810ee26.webp)

## Chi ha accesso

Il controllo **Accesso** decide chi vede la voce **Sviluppatore** nella barra
laterale e può usare le chiavi personali.

| Opzione                     | Cosa comporta                                                                                                              |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Spento**                  | Nessuno usa l'API: le chiavi esistenti, anche quelle dell'area di lavoro, vengono rifiutate con `403` finché non riaccendi |
| **Tutta l'area di lavoro**  | Ogni membro vede **Sviluppatore**. È l'impostazione di partenza                                                            |
| **Gruppi e persone scelti** | Solo le persone e i gruppi che indichi                                                                                     |

Due cose da sapere prima di restringere.

* **Gli Admin non sono esenti.** Configurano questa pagina in ogni caso, ma la
  voce **Sviluppatore** e le chiavi personali le hanno solo se sono nell'elenco.
* **Le chiavi dell'area di lavoro dipendono dall'Admin che le ha create.** Se
  restringi l'accesso e lasci fuori quell'Admin, le sue chiavi smettono di
  funzionare con `403 developer_permission_required`. Includi sempre chi ha
  creato le chiavi delle integrazioni in produzione.

Avere accesso non basta per creare chiavi personali: serve anche il permesso
**Creare chiavi API personali** in **Ruoli**, che di partenza hanno solo gli
Admin. I Membri non possono crearne in nessun caso. → [Ruoli e permessi](/ruoli)

## Le chiavi dell'area di lavoro

Le **Chiavi API workspace** servono alle integrazioni dell'azienda: si pagano con
il credito prepagato dell'area di lavoro e non consumano l'utilizzo di nessuno.
Le creano e le revocano solo gli Admin, e tutti gli Admin le vedono.

#### Premi Crea chiave API

Nella scheda **Area di lavoro**, sezione **Chiavi API workspace**. Si apre
la finestra **Crea chiave API**.

![La sezione Chiavi API workspace con il pulsante Crea chiave API evidenziato e le chiavi esistenti, con permessi, IP, data di creazione e ultimo uso](/_fern-img/5c33d5a0504c98747f41913b51d117ed8abaac40d333d0d13692688a6555d63c.webp)

#### Dai un nome e scegli i Permessi

Il nome dice dove viene usata: **Gestionale produzione**, **Staging**. In
**Permessi** scegli **Completion** (chat e completamenti), **Embedding** o
entrambi: almeno uno. Una chiave che serve solo a calcolare embedding non ha
motivo di poter generare testo.

![La finestra Crea chiave API con il nome Staging, i Permessi Completion ed Embedding spuntati, la Whitelist IP vuota con l'avviso giallo e i pulsanti Annulla e Crea](/_fern-img/0206b4f8d618fccd8db1da0a2a544b0a4f5f6d876f0ed10b3bd593789c27c6b7.webp)

#### Limita gli indirizzi

In **Whitelist IP (opzionale)** scrivi gli indirizzi o gli intervalli CIDR,
IPv4 o IPv6, dei server che la useranno, e premi **Aggiungi** per ciascuno.
Se la lasci vuota, la finestra ti avvisa che chiunque abbia la chiave può
usarla da qualsiasi rete.

![La Whitelist IP con un intervallo di esempio già aggiunto e il campo per il successivo](/_fern-img/e1eac52ad526592788d07d5f83c794d4307ce5c28548533b0bb8877b140d6f01.webp)

#### Copia la chiave e consegnala

Il valore compare una volta sola. Passalo a chi gestisce l'integrazione
attraverso un gestore di segreti, non per email o in chat.

Ogni creazione manda una notifica a tutti gli Admin e finisce nel [Registro di audit](/audit). Dal menu **⋯** di ogni riga, **Intervalli IP** cambia la
whitelist e **Revoca** spegne la chiave per sempre, dopo una conferma.

![Il menu di una chiave aperto, con Intervalli IP e Revoca in rosso](/_fern-img/88567ba37ee06adb50ac5cf4480bef296e0a59ce1701de9c814321edcf74b1c7.webp)

Le chiavi personali dei membri non compaiono qui: le vede solo chi le possiede.
La spesa che generano, invece, la vedi in **Analytics**.

Altre due impostazioni stanno in **Impostazioni › Sicurezza e controllo ›
Sicurezza e accesso** e valgono anche per l'API: la **Scadenza predefinita chiavi
API**, applicata a tutte le chiavi nuove, e le **Restrizioni di accesso IP**
dell'area di lavoro, che si sommano alla whitelist della singola chiave.
→ [Sicurezza dell'area di lavoro](/sicurezza-workspace)

> **Info**
>
> Quando rimuovi una persona dall'area di lavoro, tutte le sue chiavi vengono
> revocate, comprese quelle dell'area di lavoro che aveva creato. Prima di
> rimuovere un Admin, crea le chiavi sostitutive delle integrazioni che
> dipendono da lui. → [Invitare e gestire i membri](/membri)

## I modelli richiamabili

La sezione **Modelli API disponibili** elenca i modelli che l'API offre, con
fornitore, regione, tipo e prezzo di listino del fornitore in dollari per milione
di token. Lo stesso elenco lo vedono i membri nella scheda **I modelli
disponibili** di **Sviluppatore**.

L'interruttore **Abilitato** su ogni riga decide se le chiavi di quest'area di
lavoro possono chiamare quel modello; il contatore in alto dice quanti sono
accesi. Un modello spento sparisce da `GET /models` e le chiamate che lo
chiedono vengono rifiutate.

![Il contatore 17 di 17 modelli abilitati, i filtri Provider e Tutte le regioni, la ricerca, e le prime righe dell'elenco con id, regione, tipo, prezzi di listino per milione di token e l'interruttore Abilitato](/_fern-img/b460a4562e30566a5cac77b786ebe09d12c70408eb1fec996627ba9d7fd939cb.webp)

Questo elenco è separato dal catalogo dei modelli della chat: spegnere un modello
qui non lo toglie dal selettore dei colleghi, e viceversa.
→ [Modelli disponibili](/modelli-admin)

Finché sono tutti accesi, anche i modelli che verranno aggiunti al catalogo in
futuro saranno disponibili. Appena ne spegni uno, l'elenco diventa una scelta
esplicita e i modelli nuovi andranno accesi a mano.

> **Warning**
>
> Per bloccare l'API non spegnere i modelli uno per uno: se spegni anche l'ultimo
> rimasto acceso, l'elenco torna a valere come «tutti accesi». Per fermare tutto
> usa **Accesso** › **Spento**.

## Il tetto di spesa e i budget

Nella scheda **Costo e budget** imposti due limiti. Non sono limiti solo
dell'API: sono gli stessi che trovi in **Impostazioni › Sicurezza e controllo ›
Utilizzo**, e valgono anche per la chat.

![La scheda Costo e budget: il periodo, i riquadri Wallet, Speso in questo periodo, Tetto mensile e Richieste, la barra del Tetto mensile workspace con la matita, i totali per tipo e la tabella Budget per membro con gli importi sfocati. In alto a destra Scarica CSV evidenziato](/_fern-img/6a4ab4e0ee368a6741a70df3f948e29c9134663d005ea59e467f9140533e64e6.webp)

**Tetto mensile workspace.** È il limite di spesa dell'area di lavoro, sulla
spesa complessiva del mese. Si cambia con la matita accanto al valore, oppure si
lascia **Illimitato**. Raggiunto il tetto, le chiamate API ricevono `429` con
`api_budget_exceeded` fino al mese successivo.

**Budget per membro.** Una riga per persona, con quanto ha speso e il suo budget.
Con la matita apri **Modifica budget**: indichi l'**Importo budget (EUR)** e il
**Periodo di reset**, cioè **Giorno**, **Settimana** o **Mese**. Un budget
diverso da quello predefinito del suo piano è segnato come **personalizzato**.
Raggiunto il budget, le chiavi personali di quella persona ricevono `429` con
`member_budget_exceeded`. Il budget entra in gioco quando l'utilizzo extra è
attivo; senza, ogni persona resta dentro l'utilizzo incluso nel suo piano.

**Scarica CSV** esporta una riga per ogni chiamata del periodo: ora, chiave
mascherata, chi l'ha fatta, modello, token e costo in euro. È il file da dare a
chi deve ribaltare i costi su un progetto o un cliente.

Se l'area di lavoro non può usare l'AI, per esempio perché la prova è finita, in
cima alla scheda compare **Accesso API limitato** con il collegamento alla
fatturazione.

Le regole complete su chi paga cosa sono in [Costi, budget e analytics](/api-costi); quelle sul credito prepagato e la ricarica automatica in
[Limiti di spesa e credito](/spesa).

## La scheda Analytics

Mostra la spesa nel periodo scelto (di partenza **Questo mese**), separata fra
**Chiavi workspace** e **Chiavi personali**, con i filtri **Provider** e
**Modello**: costo, richieste e token, poi il dettaglio per fornitore e per
modello. → [Costi, budget e analytics](/api-costi)

![La scheda Analytics: le due viste Chiavi workspace e Chiavi personali, il periodo Questo mese, i filtri Provider e Modello, i riquadri Costo, Richieste, Token prompt e Token completion, e sotto il dettaglio Per provider e Per modello](/_fern-img/9a2fbb168ff078cb38ba272a010da6c60ef27f97345395f029855bd8de2bf851.webp)

## La scheda Documentazione

Contiene l'**ID area di lavoro** (le chiamate API non ne hanno bisogno: la
chiave identifica già l'area di lavoro) e
gli esempi pronti per **Chat Completions**, **Streaming**, **Tool calling**,
**Responses** ed **Embeddings**, in cURL e con gli SDK OpenAI per JavaScript e
Python. Il selettore **EU** / **Global** cambia l'indirizzo di base negli esempi.

![La scheda Documentazione: l'ID area di lavoro con Copia, le schede degli esempi da Chat Completions a Embeddings, la scelta fra cURL, JavaScript e Python e il selettore EU e Global evidenziato](/_fern-img/491420e6d9fbfd61dbc0f1d2f8d077df1544eb3f654ca50eb8d5a82c43989853.webp)