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
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).- 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. - 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. - Ruota un PAT — genera un nuovo segreto per un token esistente senza modificarne il nome; il vecchio segreto smette immediatamente di funzionare.
- Revoca un PAT — invalida il token in qualsiasi momento.
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:- Un membro richiede un PAT dalla scheda PAT (nome + scadenza).
- Gli amministratori Enterprise visualizzano la richiesta nella coda di approvazione e la approvano o la rifiutano.
- Dopo l’approvazione, il membro completa la richiesta per generare il token (visualizzato una sola volta).
- Le richieste in attesa scadono automaticamente dopo 7 giorni se non vengono gestite.
Inventario e revoca dei token
Gli amministratori Enterprise con l’autorizzazione Gestire le API key dell’account possono aprire la vista PAT inventory nella scheda Policy PAT per:- Visualizzare i PAT dell’intera enterprise, con nome, proprietario, data di creazione, data di scadenza e stato di ciascun token (Active, Revoked o Expired). È possibile filtrare per stato o cercare per nome o proprietario.
- Revocare un token attivo direttamente dalla relativa riga. L’inventario consente di revocare un solo token alla volta.
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
- Panoramica dell’autenticazione — comprendere l’intero modello di autenticazione
- Guida rapida di Teams — iniziare a usare gli utenti di servizio