Devin mette a disposizione diverse versioni dell’API con differenti meccanismi di autenticazione e modelli di autorizzazione. Comprendere quale tipo di API key utilizzare è fondamentale per una corretta integrazione.
Riepilogo delle versioni dell’API
| Versione | Autenticazione | Modello di autorizzazione |
|---|
| v1 | API key personali o di servizio | Ambito organizzativo |
| v2 | API key personali | Solo amministratori Enterprise |
| v3 (Beta) | Credenziali utente di servizio | RBAC completo |
| Tipo di API key | Prefisso | Descrizione |
|---|
| API key personale | apk_user_ | Chiavi con ambito utente-org che ereditano le autorizzazioni del singolo utente |
| API key di servizio | apk_ | Chiavi di servizio con ambito organizzazione per l’automazione |
| Credenziale utente di servizio | cog_ | Credenziali utente di servizio a livello Enterprise/organizzazione con RBAC |
- Vai a Settings > API Keys in qualsiasi sotto-organizzazione
- Fai clic su “Generate New API Key”
- Copia e archivia la chiave in modo sicuro (verrà mostrata solo una volta)
Versioni API supportate:
- v1: Sì - eredita le autorizzazioni a livello di organizzazione dell’utente
- v2: Sì - solo per utenti con ruolo di Enterprise Admin
- v3: No - usa invece le Service User Credentials
Casi d’uso consigliati:
- Script di automazione personali
- Sviluppo e test
- Integrazioni specifiche per utente
Considerazioni sulla sicurezza:
- Le chiavi sono limitate alle autorizzazioni dell’utente
- La revoca dell’accesso di un utente invalida automaticamente le sue API key
- Le chiavi dovrebbero essere ruotate regolarmente
Service API Keys (con ambito organizzativo)
- v1: Sì - con ambito organizzativo
- v2: No - non supportata
- v3: No - usa invece le Service User Credentials
Casi d’uso consigliati:
- Automazione a livello di organizzazione
- Pipeline CI/CD con ambito limitato a team specifici
- Strumenti condivisi all’interno di una sottoorganizzazione
Credenziali utente di servizio (solo v3)
- Vai su Enterprise Settings > Service Users
- Clicca su “Create Service User”
- Assegna i ruoli appropriati (Enterprise Admin, Org Admin, Org Member, ecc.)
- Genera un’API key per l’utente di servizio
Tipi di utenti di servizio:
- Enterprise Service Users: Possono accedere a più organizzazioni in base ai ruoli assegnati
- Organization Service Users: Con ambito limitato a specifiche organizzazioni con ruoli a livello di org
Versioni API supportate:
- v1: No - non disponibile
- v2: No - non disponibile
- v3: Sì - pieno supporto RBAC
Casi d’uso consigliati:
- Automazione in produzione con permessi granulari
- Flussi di lavoro multi-organizzazione
- Integrazioni sensibili alla conformità normativa che richiedono tracciabilità/audit trail
- Integrazioni di lunga durata con ambiti di permesso specifici
Considerazioni sulla sicurezza:
- Gli utenti di servizio compaiono nei log di audit separatamente dagli utenti umani
- I permessi possono essere controllati con precisione tramite RBAC
- Le chiavi possono essere ruotate senza influire sugli account utente umani
- Ideali per applicare il principio del privilegio minimo
Autenticazione con token Bearer
Authorization:
Authorization: Bearer your_api_key_here
curl -X POST "https://api.devin.ai/v1/sessions" \
-H "Authorization: Bearer YOUR_V1_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Crea un semplice script Python"
}'
curl -X GET "https://api.devin.ai/v2/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V2_ENTERPRISE_ADMIN_KEY"
curl -X GET "https://api.devin.ai/v3beta1/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V3_SERVICE_USER_KEY"
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 v3 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 della versione errata dell’API per il tipo di chiave (ad es. chiave personale con v3)
- Tentativo di accedere a risorse al di fuori del proprio ambito di autorizzazione
Soluzione:
- Per v2: assicurati di avere il ruolo di Enterprise Admin
- Per v3: utilizza una credenziale di utente di servizio con i ruoli appropriati
- Per 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 che l’URL dell’endpoint corrisponda alla versione dell’API che stai usando e che la risorsa esista.
