Vai al contenuto principale
Gli utenti di servizio sono account bot dedicati per l’accesso alle API con permessi basati sui ruoli. Questo è il metodo di autenticazione consigliato per tutte le nuove integrazioni.

​
Come funziona

  1. Crea un utente di servizio in Settings > Service users
  2. Assegna un ruolo che controlla a quali endpoint l’utente di servizio può accedere
  3. Genera una chiave API (inizia con cog_)
  4. Includi la chiave nell’header Authorization di ogni richiesta
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.
Stai passando dalle API key personali? Le API key personali (v1/v2) creavano automaticamente le sessioni a nome del tuo utente. Con gli utenti di servizio, usa create_as_user_id per ottenere lo stesso comportamento — con RBAC aggiuntivo, audit trail e gestione centralizzata delle chiavi. Vedi la panoramica dell’API per un esempio.

​
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.

​
API key legacy

Le API key legacy sono in fase di deprecazione a favore degli utenti di servizio. Consigliamo di migrare le integrazioni esistenti agli utenti di servizio. Consulta la guida alla migrazione.
Le API key legacy sono utilizzate con le API v1 e v2. Continueranno a funzionare durante il periodo di deprecazione, ma non supportano le nuove funzionalità come RBAC, attribuzione delle sessioni o paginazione basata su cursore.
Tipo di chiavePrefissoUtilizzata conDescrizione
Personal API keyapk_user_v1, v2Collegate a un account utente, ereditano le autorizzazioni dell’utente
Service API keyapk_v1Con ambito organizzativo, per l’automazione
Dove generarle: Settings > API Keys

​
Autenticazione con token Bearer

Tutte le API di Devin utilizzano l’autenticazione con token Bearer. Includi la tua chiave nell’intestazione Authorization: 
Authorization: Bearer your_api_key_here
Questo si applica sia alle credenziali dell’account di servizio sia alle API key legacy.

​
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
Soluzione: Assicurati che la tua API key sia corretta e correttamente formattata nell’header Authorization.

​
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