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

# OAuth

> Flusso del codice di autorizzazione con PKCE e credenziali client per l'accesso da server a server.

Twenty implementa OAuth 2.0 con codice di autorizzazione + PKCE per le app rivolte agli utenti e credenziali client per l'accesso da server a server. I client vengono registrati dinamicamente tramite [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) — nessuna configurazione manuale in una dashboard.

## Quando utilizzare OAuth

| Scenario | Metodo di autenticazione |
| - | - |
| Script interni, automazioni | [Chiave API](/it/developers/extend/api#authentication) |
| App esterna che agisce per conto di un utente | **OAuth — Codice di autorizzazione** |
| Da server a server, nessun contesto utente | **OAuth — Credenziali client** |
| App Twenty con estensioni dell'interfaccia utente | [App](/it/developers/extend/apps/getting-started/quick-start) (OAuth è gestito automaticamente) |

## Registrare un client

Twenty supporta la **registrazione dinamica dei client** secondo [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). Non è necessaria alcuna configurazione manuale — registra a livello di codice:

```bash theme={null}
POST /oauth/register
Content-Type: application/json

{
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "client_secret_post"
}
```

**Risposta:**

```json theme={null}
{
  "client_id": "abc123",
  "client_secret": "secret456",
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"]
}
```

<Warning>
  Conserva `client_secret` in modo sicuro — non potrà essere recuperato in seguito.
</Warning>

## Ambiti

| Ambito | Accesso |
| - | - |
| `api` | Accesso completo in lettura/scrittura alle API Core e Metadata |
| `profilo` | Legge le informazioni del profilo dell'utente autenticato |

Richiedi gli ambiti come stringa separata da spazi: `scope=api profile`

## Flusso con codice di autorizzazione

Usa questo flusso quando la tua app agisce per conto di un utente Twenty.

### 1. Reindirizza l'utente per autorizzare

```
GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  redirect_uri=https://myapp.com/callback&
  scope=api&
  state=random_state_value&
  code_challenge=CHALLENGE&
  code_challenge_method=S256
```

| Parametro | Obbligatorio | Descrizione |
| - | - | - |
| `client_id` | Sì | ID client registrato |
| `response_type` | Sì | Deve essere `code` |
| `redirect_uri` | Sì | Deve corrispondere a un URI di reindirizzamento registrato |
| `scope` | No | Ambiti separati da spazi (predefinito `api`) |
| `stato` | Consigliato | Stringa casuale per prevenire attacchi CSRF |
| `code_challenge` | Consigliato | Challenge PKCE (hash SHA-256 del verifier, codificato in base64url) |
| `code_challenge_method` | Consigliato | Deve essere `S256` quando si usa PKCE |

L'utente vede una schermata di consenso e approva o nega l'accesso.

### 2. Gestisci la callback

Dopo l'autorizzazione, Twenty reindirizza al tuo `redirect_uri`:

```
https://myapp.com/callback?code=AUTH_CODE&state=random_state_value
```

Verifica che `state` corrisponda a quanto inviato.

### 3. Scambia il codice con i token

```bash theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://myapp.com/callback&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=YOUR_PKCE_VERIFIER
```

**Risposta:**

```json theme={null}
{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh..."
}
```

### 4. Usa il token di accesso

```bash theme={null}
GET /rest/companies
Authorization: Bearer ACCESS_TOKEN
```

### 5. Aggiorna alla scadenza

```bash theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET
```

## Flusso delle credenziali del client

Per integrazioni da server a server senza interazione dell'utente:

```bash theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=api
```

Il token restituito ha accesso a livello di spazio di lavoro, non legato a un utente specifico.

## Scoperta del server

Twenty pubblica la propria configurazione OAuth in un endpoint di discovery standard:

```
GET /.well-known/oauth-authorization-server
```

Questo restituisce tutti gli endpoint, i tipi di grant supportati, gli ambiti e le funzionalità — utile per creare client OAuth generici.

## Riepilogo degli endpoint API

| Endpoint | Scopo |
| - | - |
| `/.well-known/oauth-authorization-server` | Individuazione dei metadati del server |
| `/oauth/register` | Registrazione dinamica dei client |
| `/oauth/authorize` | Autorizzazione utente |
| `/oauth/token` | Scambio e aggiornamento dei token |

| Ambiente | URL di base |
| - | - |
| **Cloud** | `https://api.twenty.com` |
| **Auto-ospitato** | `https://{your-domain}` |

## OAuth vs Chiavi API

| | API Keys | OAuth |
| - | - | - |
| **Impostazione** | Genera nelle Impostazioni | Registra un client, implementa il flusso |
| **Contesto utente** | Nessuno (a livello di spazio di lavoro) | Autorizzazioni dell'utente specifico |
| **Ideale per** | Script, strumenti interni | App esterne, integrazioni multiutente |
| **Rotazione dei token** | Manuale | Automatica tramite token di refresh |
| **Accesso con ambiti** | Accesso completo alle API | Granulare tramite ambiti |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.