Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.devin.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

PrincipalTokenDescrizione
Utente di servizio (non umano)Chiave dell’utente di servizioPer integrazioni automatizzate e pipeline CI/CD
Utente (umano)token di accesso personale (PAT)Per l’accesso programmatico umano con la propria identità
Tutte le credenziali API usano il formato con prefisso cog_. Includi il tuo token nell’Authorization header di ogni richiesta: 
curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer cog_your_token_here"
La distinzione fondamentale è quale principal il token autentica:
  • Una chiave 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.
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
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a simple Python script"}'

​
Ambiti degli utenti di servizio

AmbitoCreato inAccesso APICaso d’uso
OrganizationSettings > Service users/v3/organizations/*Gestione delle sessioni, knowledge, playbook, secret
EnterpriseEnterprise settings > Service users/v3/enterprise/* + /v3/organizations/*Gestione tra organizzazioni, analytics, log di audit, fatturazione
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 (beta chiusa)

I token di accesso personali sono attualmente in beta chiusa e sono abilitati tramite feature flag. Contatta il supporto per ottenere l’accesso. I PAT non sono disponibili per gli account SSO/Enterprise.
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. 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.
Tipo di chiavePrefissoUtilizzata conDescrizione
Chiave personaleapk_user_v1, v2Collegata a un account utente, eredita le autorizzazioni dell’utente
Chiave di servizioapk_v1Con ambito organizzativo, per l’automazione
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