> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticazione

> Comprendi principal, token e come autenticarti con l'API di Devin

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.

<div id="principals-tokens">
  ## Principal & token
</div>

| 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à |

Tutte le credenziali API usano il formato con prefisso `cog_`. Includi il tuo token nell'`Authorization` header di ogni richiesta:

```bash theme={null}
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.

***

<div id="service-users-recommended-for-automation">
  ## Utenti di servizio (consigliati per l'automazione)
</div>

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.

<div id="how-it-works">
  ### Come funziona
</div>

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

```bash theme={null}
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"}'
```

<div id="service-user-scopes">
  ### Ambiti degli utenti di servizio
</div>

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

<Tip>
  Trova l'ID della tua organizzazione nella pagina **Settings > Service Users**.
</Tip>

<div id="session-attribution-with-create_as_user_id">
  ### Attribuzione delle sessioni con `create_as_user_id`
</div>

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.

<div id="key-properties">
  ### Proprietà principali delle chiavi
</div>

* 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](/it/api-reference/getting-started/teams-quickstart) o la [Guida rapida Enterprise](/it/api-reference/getting-started/enterprise-quickstart).

***

<div id="personal-access-tokens-closed-beta">
  ## Token di accesso personali (beta chiusa)
</div>

<Note>
  I token di accesso personali sono attualmente in **beta chiusa** e sono abilitati tramite feature flag. [Contatta il supporto](mailto:support@cognition.ai) per ottenere l'accesso. I PAT non sono disponibili per gli account SSO/Enterprise.
</Note>

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](/it/api-reference/personal-access-tokens).

***

<div id="legacy-authentication-deprecated">
  ## Autenticazione legacy (deprecata)
</div>

<Warning>
  Le chiavi legacy sono deprecate. Usa [API v3](/it/api-reference/v3/overview) con l'autenticazione tramite utente di servizio. Consulta la [guida alla migrazione](/it/api-reference/getting-started/migration-guide).
</Warning>

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

**Dove generarle:** [Settings > API Keys](https://app.devin.ai/settings/api-keys)

***

<div id="security-best-practices">
  ## Migliori pratiche di sicurezza
</div>

<Warning>
  Non condividere mai le API key in aree accessibili pubblicamente come repository GitHub, codice lato client o log.
</Warning>

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

<div id="troubleshooting">
  ## Risoluzione dei problemi
</div>

<div id="401-unauthorized">
  ### 401 Non autorizzato
</div>

**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](/it/work-with-devin/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).

<div id="403-forbidden">
  ### 403 Forbidden
</div>

**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

<div id="404-not-found">
  ### 404 Non trovato
</div>

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

<div id="next-steps">
  ## Prossimi passi
</div>

* [Teams guida rapida](/it/api-reference/getting-started/teams-quickstart) — inizia in pochi minuti
* [Enterprise guida rapida](/it/api-reference/getting-started/enterprise-quickstart) — configurazione di RBAC e organizzazioni multiple
* [Flussi comuni](/it/api-reference/common-flows) — esempi di flussi di lavoro end-to-end
* [Guida alla migrazione](/it/api-reference/getting-started/migration-guide) — esegui la migrazione da v1/v2