Skip to main content

​
Panoramica

I token di accesso personale (PAT) consentono agli utenti umani di autenticarsi a livello di codice con la propria identità. A differenza delle API key dell’utente di servizio (che autenticano come un utente di servizio non umano), un token di accesso personale autentica come te — l’utente umano che ha creato il token. Tutte le credenziali API usano il formato con prefisso cog_. Entrambi i tipi di token vengono usati nello stesso modo nell’header Authorization:

​
Ambito e autorizzazioni

Un PAT è associato a te, nell’ambito del tuo account (account Teams o enterprise). Non è legato a una singola organizzazione e non esistono “PAT dell’organizzazione” o “PAT enterprise”. A differenza degli utenti di servizio, che vengono creati a livello di organizzazione o di enterprise. Ogni richiesta seleziona l’organizzazione. Gli endpoint dell’organizzazione la specificano nel percorso URL (/v3/organizations/{org_id}/...) e la richiesta viene autorizzata in base al tuo accesso e al tuo ruolo in quell’organizzazione. Una richiesta rivolta a un’organizzazione a cui non hai accesso non riesce. Il token ha le stesse autorizzazioni del tuo utente. Tutto ciò che puoi fare nella web app puoi farlo con il tuo PAT, e nulla di più. Per creare, ruotare o revocare PAT, devi disporre dell’autorizzazione Manage API keys nell’organizzazione di cui stai visualizzando le impostazioni oppure dell’autorizzazione Gestire le API key dell’account a livello di account. Questa autorizzazione determina chi può gestire i token; non modifica ciò che un token può fare. Gli account Enterprise dispongono anche di un’organizzazione interna che archivia solo le impostazioni a livello Enterprise. Non è un workspace. Le richieste PAT indirizzate a tale organizzazione vengono rifiutate con 403, quindi usa sempre l’ID di un’organizzazione figlia.

​
Quando usare i PAT

I PAT sono pensati per gli scenari in cui ti serve un accesso programmatico all’API a tuo nome:
  • Script e strumenti personali — automatizza i tuoi flussi di lavoro senza un utente di servizio condiviso
  • Sviluppo locale — testa le integrazioni API usando il tuo account
  • Automazione di breve durata — script una tantum che devono essere attribuiti a te
Per le integrazioni in produzione, le pipeline CI/CD e l’automazione condivisa, usa invece le API key degli utenti di servizio. Gli utenti di servizio offrono tracce di audit migliori, gestione centralizzata delle chiavi e controlli RBAC. Se non sai quale usare, consulta il confronto.

​
Creazione e gestione dei PAT

Gestisci i tuoi PAT dalla scheda PATs nella pagina Settings di Devin API, in qualsiasi organizzazione o in Settings Enterprise. La scheda mostra gli stessi token in entrambi i casi (vedi Ambito e autorizzazioni).
  1. Crea un PAT — assegnagli un nome e una data di scadenza. Il token inizia con cog_ e viene visualizzato una sola volta, al momento della creazione.
  2. Usa il token nell’header Authorization — esattamente come un’API key di un utente di servizio. Ogni chiamata API viene autenticata con il tuo account utente: si applicano le tue autorizzazioni, le tue appartenenze alle org e la tua traccia di audit.
  3. Ruota un PAT — genera un nuovo segreto per un token esistente senza modificarne il nome; il vecchio segreto smette immediatamente di funzionare.
  4. Revoca un PAT — invalida il token in qualsiasi momento.
I PAT sono accettati anche dagli endpoint in tempo reale, come l’ACP live WebSocket; pertanto, strumenti come Devin CLI e i client desktop possono autenticarsi con un PAT.

​
Governance Enterprise

Per gli account Enterprise, la disponibilità dei PAT è regolata da una policy PAT a livello Enterprise, applicata a tutte le organizzazioni dell’Enterprise. Gli amministratori Enterprise con Gestisci le Settings Enterprise configurano la policy (e gestiscono le richieste di approvazione) nella scheda Policy PAT della pagina delle Settings di Devin API dell’Enterprise.

​
Modalità delle policy

​
Policy di scadenza

Quando i PAT sono abilitati per un account Enterprise, ogni PAT deve avere una data di scadenza, entro la durata massima prevista dalla policy (365 giorni per impostazione predefinita; gli amministratori possono configurare un limite più breve). Gli account non Enterprise (Teams) possono creare PAT senza scadenza.

​
Flusso di approvazione

Con Approvazione richiesta:
  1. Un membro richiede un PAT dalla scheda PAT (nome + scadenza).
  2. Gli amministratori Enterprise visualizzano la richiesta nella coda di approvazione e la approvano o la rifiutano.
  3. Dopo l’approvazione, il membro completa la richiesta per generare il token (visualizzato una sola volta).
  4. Le richieste in attesa scadono automaticamente dopo 7 giorni se non vengono gestite.
I richiedenti e gli amministratori ricevono notifiche via email in ogni fase del ciclo di vita del token (richiesto, approvato, rifiutato, revocato).

​
Inventario e revoca dei token

Gli amministratori Enterprise con l’autorizzazione Gestire le API key dell’account possono:
  • Visualizzare tutti i PAT dell’Enterprise nell’inventario dei token, incluso lo stato di conformità alla policy corrente
  • Revocare in blocco i token (ad es. dopo aver reso più restrittiva la policy)
Rendere più restrittiva la policy (o disabilitare i PAT) annulla le richieste in sospeso interessate e l’inventario segnala i token esistenti che non sono più conformi.

​
Revoca automatica

I PAT di un utente vengono revocati automaticamente quando l’utente non fa più parte dell’account, anche in caso di rimozione tramite deprovisioning SCIM o modifiche ai gruppi IdP.

​
Considerazioni sulla sicurezza

  • Tratta i PAT con la stessa cura riservata alle password: forniscono pieno accesso al tuo account
  • Conserva i PAT nelle variabili d’ambiente o in un gestore di segreti, mai nel codice sorgente
  • Imposta la scadenza più breve adatta al tuo caso d’uso
  • Revoca immediatamente i PAT se risultano compromessi
  • Per qualsiasi automazione condivisa o di produzione, preferisci le API key di un utente di servizio

​
Passaggi successivi