Skip to main content
L’API di Devin usa un modello principal + token. Un principal identifica chi sei (la tua identità) e un token è il modo in cui lo dimostri (la tua credenziale). Comprendere questa distinzione è fondamentale per scegliere il metodo di autenticazione giusto per il tuo caso d’uso.

​
Principal & token

Tutte le credenziali API usano il formato con prefisso cog_. Includi il tuo token nell’Authorization header di ogni richiesta:
La distinzione fondamentale è quale principal il token autentica:
  • Una API key dell’utente di servizio autentica come utente di servizio — si applicano l’identità, le autorizzazioni e le appartenenze alle org dell’utente di servizio.
  • Un token di accesso personale autentica come utente umano che lo ha creato — si applicano l’identità, le autorizzazioni e le appartenenze alle org di quell’utente.

​
Token di accesso personale o utente di servizio?

Regola generale: se l’integrazione deve continuare a funzionare dopo che lasci il team o cambi ruolo, usa un utente di servizio. Se deve fare esattamente ciò che puoi fare tu, usando le tue autorizzazioni, usa un PAT.
Gli utenti di servizio sono account non umani progettati per le integrazioni tramite API. Possono ricevere autorizzazioni specifiche tramite RBAC ed essere aggiunti alle organizzazioni in modo indipendente dagli utenti umani.

​
Come funziona

  1. Crea un utente di servizio in Settings > Service users (organizzazione) o Enterprise settings > Service users (enterprise)
  2. Assegna un ruolo che controlla a quali endpoint l’utente di servizio può accedere
  3. Genera una chiave — la chiave inizia con cog_ e viene mostrata una sola volta al momento della creazione
  4. Usa la chiave nell’header Authorization di ogni richiesta API

​
Ambiti degli utenti di servizio

Trova l’ID della tua organizzazione nella pagina Settings > Service Users.

​
Attribuzione delle sessioni con create_as_user_id

Gli utenti di servizio sono identità separate rispetto agli utenti umani. Per impostazione predefinita, le sessioni create da un utente di servizio sono attribuite all’utente di servizio stesso. Per creare sessioni per conto di un utente specifico, passa il parametro create_as_user_id quando crei una sessione. La sessione apparirà nell’elenco delle sessioni di quell’utente e verrà conteggiata nel suo utilizzo. Questo richiede l’autorizzazione ImpersonateOrgSessions nel ruolo dell’utente di servizio.

​
Proprietà principali delle chiavi

  • Le chiavi iniziano con cog_ e vengono mostrate una sola volta al momento della creazione
  • Gli utenti di servizio compaiono separatamente dagli utenti umani nei log di audit
  • Le autorizzazioni sono gestite tramite RBAC — assegna solo i permessi strettamente necessari all’integrazione
  • Gli utenti di servizio Enterprise ereditano le autorizzazioni a livello di organizzazione per tutte le organizzazioni
Per istruzioni dettagliate sulla configurazione, consulta la Guida rapida per i team o la Guida rapida Enterprise.

​
Token di accesso personali

I token di accesso personali (PAT) consentono agli utenti umani di autenticarsi programmaticamente con la propria identità. Quando usi un PAT, l’API vede te — le tue autorizzazioni, la tua appartenenza alle org e la tua traccia di audit. Questa opzione è utile quando vuoi effettuare chiamate API a tuo nome (ad esempio, script personali o strumenti locali) anziché tramite un utente di servizio condiviso. Un PAT non è vincolato a un’organizzazione o a un account Enterprise. Ti appartiene all’interno del tuo account e funziona in ogni organizzazione a cui hai accesso. Ogni richiesta specifica un’organizzazione nell’URL e il tuo ruolo in tale organizzazione determina cosa può fare la richiesta. Per gli account Enterprise, i PAT sono disciplinati da una policy a livello Enterprise (disabilitata per impostazione predefinita), configurata dagli amministratori Enterprise e comprensiva di un flusso di lavoro di approvazione e della scadenza obbligatoria dei token. Per maggiori dettagli, vedi Token di accesso personali.

​
Autenticazione legacy (deprecata)

Le chiavi legacy sono deprecate. Usa API v3 con l’autenticazione tramite utente di servizio. Consulta la guida alla migrazione.
Le chiavi legacy sono utilizzate con le API v1 e v2. Continuano a funzionare durante il periodo di deprecazione, ma non supportano nuove funzionalità come RBAC, attribuzione delle sessioni o paginazione basata su cursore. Dove generarle: Settings > API Keys

​
Migliori pratiche di sicurezza

Non condividere mai le API key in aree accessibili pubblicamente come repository GitHub, codice lato client o log.
  1. Conserva le chiavi in modo sicuro: Usa variabili d’ambiente o sistemi di gestione dei segreti
  2. Ruota regolarmente le chiavi: Genera nuove chiavi e revoca periodicamente quelle vecchie
  3. Usa utenti di servizio per l’automazione: Preferisci gli utenti di servizio alle chiavi personali in produzione
  4. Applica il principio del privilegio minimo: Concedi solo le autorizzazioni strettamente necessarie
  5. Monitora l’utilizzo: Controlla i log di audit per individuare attività API inattese
  6. Revoca immediatamente le chiavi compromesse: Se una chiave viene esposta, revocala e generane una nuova

​
Risoluzione dei problemi

​
401 Non autorizzato

Possibili cause:
  • API key non valida o scaduta
  • Header Authorization mancante
  • Formato del token Bearer errato
  • Utilizzo di un’API key legacy (apk_ / apk_user_) con Devin MCP — sono supportate solo le chiavi con prefisso cog_
Soluzione: Assicurati che la tua API key sia corretta e correttamente formattata nell’header Authorization. Per l’utilizzo di MCP, assicurati di usare una chiave dell’utente di servizio (non una chiave legacy).

​
403 Forbidden

Possibili cause:
  • L’API key non dispone delle autorizzazioni richieste
  • Utilizzo del tipo di chiave errato per l’endpoint (ad es. chiave legacy con endpoint v3)
  • Tentativo di accedere a risorse al di fuori del proprio ambito di autorizzazione
Soluzione:
  • Assicurati che il tuo utente di servizio abbia il ruolo e le autorizzazioni corrette
  • Per gli endpoint legacy v2: assicurati di avere il ruolo di Enterprise Admin
  • Per gli endpoint legacy v1: verifica di avere accesso all’organizzazione

​
404 Non trovato

Possibili cause:
  • URL dell’endpoint API errato
  • La risorsa non esiste oppure non disponi dei permessi di accesso
Soluzione: Verifica l’URL dell’endpoint e che la risorsa esista.

​
Prossimi passi