Guida rapida: Enterprise

Questa guida illustra come configurare l’accesso all’API per organizzazioni Enterprise con ruoli personalizzati, RBAC e supporto multi-organizzazione.

Se sei su un piano Teams con una singola organizzazione e non hai bisogno di ruoli personalizzati, la guida rapida per Teams è più semplice.

Se sei un cliente Devin Enterprise con una distribuzione dedicata, dovrai sostituire api.devin.ai in tutti gli URL API con il dominio API personalizzato della tua organizzazione (ad esempio api.your-company.devinenterprise.com). Contatta l’amministratore Devin della tua organizzazione o il supporto di Cognition se non sei sicuro del tuo dominio API.

Comprendere gli ambiti degli utenti di servizio

I clienti Enterprise possono creare utenti di servizio su due livelli:

Ambito	Base URL	Caso d’uso
Enterprise	`/v3/enterprise/*`	Gestione multi‑organizzazione, analisi, log di audit, gestione dei membri
Organization	`/v3/organizations/{org_id}/*`	Sessioni, Knowledge, playbook, segreti all’interno di una singola organizzazione

Un utente di servizio Enterprise con autorizzazioni a livello Enterprise eredita automaticamente le corrispondenti autorizzazioni a livello di organizzazione in tutte le organizzazioni.

Passaggio 1: Crea un account di servizio

Utente di servizio Enterprise (accesso multi-organizzazione)

Vai su Enterprise settings > Service users
Fai clic su Create service user
Scegli un nome (ad es. “Analytics Dashboard”, “Org Provisioning Bot”)
Assegna un ruolo Enterprise con le autorizzazioni richieste dalla tua integrazione

Utente di servizio dell’organizzazione (accesso a una singola organizzazione)

Vai a Settings > Service users all’interno dell’organizzazione di destinazione
Fai clic su Create service user
Scegli un nome e assegna un ruolo a livello di organizzazione

Segui il principio del minimo privilegio: crea utenti di servizio con ambito di organizzazione quando la tua integrazione ha bisogno di accedere a una sola organizzazione. Usa utenti di servizio Enterprise solo per flussi di lavoro tra più organizzazioni.

Passaggio 2: Genera un’API key

Dopo aver creato l’utente di servizio, fai clic su Generate API key
Copia subito la chiave — inizia con cog_ e non verrà più mostrata
Conservala in modo sicuro come variabile d’ambiente:

export DEVIN_API_KEY="cog_your_key_here"

Passaggio 3: Esegui la tua prima chiamata API

Esempio di endpoint Enterprise

Elenca tutte le organizzazioni del tuo account Enterprise:

curl "https://api.devin.ai/v3/enterprise/organizations" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Esempio di endpoint di organizzazione

Crea una sessione di Devin in una specifica organizzazione:

export DEVIN_ORG_ID="your_org_id"

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": "Implement the feature described in JIRA-123"}'

Autorizzazioni e RBAC

Ogni endpoint API è protetto da una specifica autorizzazione. L’autorizzazione richiesta è documentata nella pagina di riferimento API di ciascun endpoint. Le autorizzazioni sono suddivise in due ambiti:

Autorizzazioni Enterprise — controllano gli endpoint /v3/enterprise/* (ad es. ManageOrganizations, ManageBilling, ViewAccountMetrics)
Autorizzazioni dell’organizzazione — controllano gli endpoint /v3/organizations/{org_id}/* (ad es. UseDevinSessions, ManageOrgSecrets, ManageOrgPlaybooks)

Un utente di servizio Enterprise con un’autorizzazione a livello Enterprise eredita automaticamente la corrispondente autorizzazione a livello di organizzazione in tutte le organizzazioni. Ad esempio, ViewAccountSessions concede ViewOrgSessions in ogni organizzazione. Per la documentazione completa sulle autorizzazioni, consulta la documentazione sulle autorizzazioni e RBAC.

Flussi di lavoro Enterprise più comuni

Monitorare il consumo nelle varie organizzazioni

# Ottieni il riepilogo giornaliero dei consumi (usa timestamp Unix — esempio: 1 gen - 31 gen 2025)
curl "https://api.devin.ai/v3/enterprise/consumption/daily?time_after=1735689600&time_before=1738368000" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Recupero dei log di audit

curl "https://api.devin.ai/v3/enterprise/audit-logs" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Gestisci gli utenti tra più organizzazioni

# Elenca gli utenti Enterprise
curl "https://api.devin.ai/v3/enterprise/members/users" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

# Elenca gli utenti in un'organizzazione specifica
curl "https://api.devin.ai/v3/enterprise/organizations/$DEVIN_ORG_ID/members/users" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Prossimi passi

Esplora la documentazione completa sulle autorizzazioni API
Approfondisci l’autenticazione
Configura la paginazione per insiemi di risultati di grandi dimensioni
Consulta la guida alla migrazione se stai eseguendo la migrazione da v1/v2

​Comprendere gli ambiti degli utenti di servizio

​Passaggio 1: Crea un account di servizio

​Utente di servizio Enterprise (accesso multi-organizzazione)

​Utente di servizio dell’organizzazione (accesso a una singola organizzazione)

​Passaggio 2: Genera un’API key

​Passaggio 3: Esegui la tua prima chiamata API

​Esempio di endpoint Enterprise

​Esempio di endpoint di organizzazione

​Autorizzazioni e RBAC

​Flussi di lavoro Enterprise più comuni

​Monitorare il consumo nelle varie organizzazioni

​Recupero dei log di audit

​Gestisci gli utenti tra più organizzazioni

​Prossimi passi

Comprendere gli ambiti degli utenti di servizio

Passaggio 1: Crea un account di servizio

Utente di servizio Enterprise (accesso multi-organizzazione)

Utente di servizio dell’organizzazione (accesso a una singola organizzazione)

Passaggio 2: Genera un’API key

Passaggio 3: Esegui la tua prima chiamata API

Esempio di endpoint Enterprise

Esempio di endpoint di organizzazione

Autorizzazioni e RBAC

Flussi di lavoro Enterprise più comuni

Monitorare il consumo nelle varie organizzazioni

Recupero dei log di audit

Gestisci gli utenti tra più organizzazioni

Prossimi passi