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 | Descrizione |
|---|
| Utente di servizio (non umano) | Chiave dell’utente di servizio | Per integrazioni automatizzate e pipeline CI/CD |
| Utente (umano) | token di accesso personale (PAT) | Per l’accesso programmatico umano con la propria identità |
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"
- 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.
Utenti di servizio (consigliati per l’automazione)
- Crea un utente di servizio in Settings > Service users (organizzazione) o Enterprise settings > Service users (enterprise)
- Assegna un ruolo che controlla a quali endpoint l’utente di servizio può accedere
- Genera una chiave — la chiave inizia con
cog_ e viene mostrata una sola volta al momento della creazione
- 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
| Ambito | Creato in | Accesso API | Caso d’uso |
|---|
| Organization | Settings > Service users | /v3/organizations/* | Gestione delle sessioni, knowledge, playbook, secret |
| Enterprise | Enterprise 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
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.
Autenticazione legacy (deprecata)
| Tipo di chiave | Prefisso | Utilizzata con | Descrizione |
|---|
| Chiave personale | apk_user_ | v1, v2 | Collegata a un account utente, eredita le autorizzazioni dell’utente |
| Chiave di servizio | apk_ | v1 | Con ambito organizzativo, per l’automazione |
Migliori pratiche di sicurezza
Non condividere mai le API key in aree accessibili pubblicamente come repository GitHub, codice lato client o log.
- Conserva le chiavi in modo sicuro: Usa variabili d’ambiente o sistemi di gestione dei segreti
- Ruota regolarmente le chiavi: Genera nuove chiavi e revoca periodicamente quelle vecchie
- Usa utenti di servizio per l’automazione: Preferisci gli utenti di servizio alle chiavi personali in produzione
- Applica il principio del privilegio minimo: Concedi solo le autorizzazioni strettamente necessarie
- Monitora l’utilizzo: Controlla i log di audit per individuare attività API inattese
- Revoca immediatamente le chiavi compromesse: Se una chiave viene esposta, revocala e generane una nuova
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.
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
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.
