Vai al contenuto principale
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 — nessuna configurazione manuale in una dashboard.

​
Quando utilizzare OAuth

ScenarioMetodo di autenticazione
Script interni, automazioniChiave API
App esterna che agisce per conto di un utenteOAuth — Codice di autorizzazione
Da server a server, nessun contesto utenteOAuth — Credenziali client
App Twenty con estensioni dell’interfaccia utenteApp (OAuth è gestito automaticamente)

​
Registrare un client

Twenty supporta la registrazione dinamica dei client secondo RFC 7591. Non è necessaria alcuna configurazione manuale — registra a livello di codice: 
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: 
{
  "client_id": "abc123",
  "client_secret": "secret456",
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"]
}
Conserva client_secret in modo sicuro — non potrà essere recuperato in seguito.

​
Ambiti

AmbitoAccesso
apiAccesso completo in lettura/scrittura alle API Core e Metadata
profiloLegge 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
ParametroObbligatorioDescrizione
client_idSìID client registrato
response_typeSìDeve essere code
redirect_uriSìDeve corrispondere a un URI di reindirizzamento registrato
scopeNoAmbiti separati da spazi (predefinito api)
statoConsigliatoStringa casuale per prevenire attacchi CSRF
code_challengeConsigliatoChallenge PKCE (hash SHA-256 del verifier, codificato in base64url)
code_challenge_methodConsigliatoDeve 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

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: 
{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh..."
}

​
4. Usa il token di accesso

GET /rest/companies
Authorization: Bearer ACCESS_TOKEN

​
5. Aggiorna alla scadenza

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

EndpointScopo
/.well-known/oauth-authorization-serverIndividuazione dei metadati del server
/oauth/registerRegistrazione dinamica dei client
/oauth/authorizeAutorizzazione utente
/oauth/tokenScambio e aggiornamento dei token
AmbienteURL di base
Cloudhttps://api.twenty.com
Auto-ospitatohttps://{your-domain}

​
OAuth vs Chiavi API

API KeysOAuth
ImpostazioneGenera nelle ImpostazioniRegistra un client, implementa il flusso
Contesto utenteNessuno (a livello di spazio di lavoro)Autorizzazioni dell’utente specifico
Ideale perScript, strumenti interniApp esterne, integrazioni multiutente
Rotazione dei tokenManualeAutomatica tramite token di refresh
Accesso con ambitiAccesso completo alle APIGranulare tramite ambiti