Ogni richiesta all’API e al server MCP richiede una chiave API. Una chiave appartiene a un solo spazio di lavoro, agisce come il proprietario o l’amministratore che l’ha creata e può raggiungere solo gli endpoint consentiti dai suoi permessi. Le chiavi hanno la forma gr_live_ seguito da 43 lettere, cifre, trattini e trattini bassi.
Creare una chiave
- 1
Apri API e agenti
In Gradiently, vai in Impostazioni › API e agenti e scegli lo spazio di lavoro a cui è destinata la chiave. Solo i proprietari e gli amministratori di quello spazio di lavoro possono creare chiavi.
- 2
Dalle un nome
In Crea una chiave, dalle un Nome che dica dove la userai, come Claude Code o Esportazione notturna, così saprai quale revocare più avanti.
- 3
Scegli cosa può fare
In Cosa può fare, seleziona i permessi di cui ha bisogno, almeno uno. La sezione successiva li spiega uno per uno.
- 4
Copiala una volta
Seleziona Crea chiave. La chiave compare in Copia la tua chiave ora, ed è l’unica volta in cui viene mostrata. Copiala in un gestore di password o nel tuo archivio di segreti, poi seleziona L’ho salvata.
Chi ha creato una chiave riceve un’email quando viene creata e quando viene revocata, con il nome, l’inizio della chiave e i suoi permessi. L’elenco nelle Impostazioni mostra per ogni chiave attiva il nome, l’inizio della chiave, quando è stata usata l’ultima volta e quanti permessi ha.
Permessi
Un permesso (scope) consente una sola cosa. Una richiesta ha bisogno di tutti i permessi elencati dal suo endpoint, e ogni strumento MCP ha bisogno dei permessi di tutte le richieste che fa. Concedi solo ciò che serve al lavoro.
| Permesso | Nelle Impostazioni | Cosa consente |
|---|---|---|
designs:read | Leggere i design | Leggere brand, design, miniature e caricamenti, generare i design e seguire le serie del Designer. |
designs:write | Creare e modificare i design | Creare, modificare, duplicare, condividere ed eliminare design, caricare ed eliminare immagini, e usare il Designer. |
marks:read | Cercare i Mark | Cercare nel Mercato, leggere i Mark e le tue bozze, costruire e verificare ricette, e leggere le versioni dei Mark. |
marks:claim | Riservare i Mark | Riservare un Mark disponibile, o uno che un altro titolare ha messo in vendita, per chi ha creato la chiave. |
brand:generate | Generare brand | Generare e adottare brand, salvare e modificare Mark in bozza, e gestire le versioni dei Mark. |
workspaces:read | Leggere il workspace | Leggere lo spazio di lavoro, i suoi membri e il registro attività. Con designs:read, leggere /api/me. |
personalities:write | Modificare i brand | Creare, rinominare ed eliminare brand, e cambiare il Mark, il profilo e lo stile di un brand. |
members:write | Invitare membri | Inviare inviti per entrare nello spazio di lavoro. |
Le nuove chiavi partono con Leggere i design, Creare e modificare i design, Cercare i Mark e Generare brand già selezionati. Riservare i Mark resta disattivato finché non lo scegli, perché una riserva rende te, che hai creato la chiave, il titolare di un Mark.
Ruotare una chiave
Le chiavi non scadono, e il nome e i permessi di una chiave non si possono cambiare dopo la creazione. Per ruotare una chiave, o per cambiare cosa può fare, sostituiscila:
- 1
Crea la nuova chiave
Crea una chiave con i permessi che vuoi, con un nome che la distingua da quella vecchia.
- 2
Passa i tuoi strumenti alla nuova chiave
Metti la nuova chiave in ogni posto in cui usavi quella vecchia: il tuo client MCP, l’archivio di segreti o le impostazioni di deploy.
- 3
Revoca la vecchia chiave
Quando la data usata della vecchia chiave smette di cambiare nell’elenco, revocala.
Revocare una chiave
In Impostazioni › API e agenti, seleziona Revoca accanto alla chiave e conferma con Revoca chiave. Tutto ciò che la usa smette subito di funzionare, e non si può annullare. I proprietari e gli amministratori dello spazio di lavoro possono revocare qualsiasi sua chiave.
Una chiave smette di funzionare anche da sola quando chi l’ha creata lascia lo spazio di lavoro, scende sotto il ruolo di amministratore o ha l’account disattivato. Le chiavi create da una persona vengono revocate quando viene rimossa dallo spazio di lavoro o retrocessa.
Cosa una chiave non può mai fare
Alcune cose richiedono sempre una persona che ha eseguito l’accesso a Gradiently, qualunque siano i permessi della chiave:
- Creare, elencare o revocare chiavi.
- Modificare l’account: profilo, email, password, sessioni di accesso, o eliminarlo.
- Accedere alla fatturazione: piani, checkout, pagamenti, ricariche di crediti IA, Saldo e pagamenti ricevuti. Una riserva o un acquisto che richiede un pagamento si ferma e chiede di completare il checkout in Gradiently.
- Cedere un Mark: trasferirlo a qualcun altro, rilasciarlo, metterlo in vendita, rinnovarlo o pubblicarlo.
- Spostare su uno spazio di lavoro la titolarità o la licenza di un Mark. I Mark riservati da una chiave appartengono a chi l’ha creata, e ogni licenza resta sua.
- Cambiare chi fa parte dello spazio di lavoro o i ruoli, rinominare, trasferire o eliminare lo spazio di lavoro. Con
members:writepuò solo inviare inviti. - Raggiungere uno spazio di lavoro diverso dal suo, nemmeno uno di cui fa parte chi l’ha creata.
- Usare l’amministrazione di Gradiently.
Tenere al sicuro le chiavi
Da fare
- Crea una chiave per ogni strumento o assistente, con il suo nome.
- Concedi il minor numero di permessi che basta per il lavoro.
- Tieni le chiavi in un gestore di password, in un archivio di segreti o in una variabile d’ambiente.
- Revoca una chiave appena sospetti che sia trapelata, poi creane una nuova.
- Controlla ogni tanto le date di ultimo utilizzo, e revoca le chiavi che nessuno usa.
Da evitare
- Fare commit di una chiave in un repository o incollarla in un file di configurazione condiviso.
- Mettere una chiave in una pagina web, in un’app mobile o in qualsiasi cosa che giri sul dispositivo di qualcun altro.
- Condividere una chiave tra persone o strumenti.
- Inviare una chiave via email o in chat.
- Lasciare attivo Riservare i Mark su una chiave che non riserva.
Gradiently conserva solo un hash di ogni chiave e il suo inizio da mostrare, quindi una chiave persa non si può mostrare di nuovo: revocala e creane un’altra. Se pensi che una chiave sia stata usata in modo improprio, revocala e diccelo.
