Zum Hauptinhalt springen
Twenty implementiert OAuth 2.0 mit Autorisierungscode + PKCE für benutzerorientierte Apps und Client-Anmeldedaten für Server-zu-Server-Zugriff. Clients werden dynamisch über RFC 7591 registriert — keine manuelle Einrichtung in einem Dashboard.

​
Wann Sie OAuth verwenden sollten

SzenarioAuthentifizierungsmethode
Interne Skripte, AutomatisierungAPI-Schlüssel
Externe App, die im Namen eines Benutzers handeltOAuth — Autorisierungscode
Server-zu-Server, kein BenutzerkontextOAuth — Client-Anmeldedaten
Twenty-App mit UI-ErweiterungenApps (OAuth wird automatisch gehandhabt)

​
Einen Client registrieren

Twenty unterstützt die dynamische Client-Registrierung gemäß RFC 7591. Keine manuelle Einrichtung erforderlich — registrieren Sie den Client programmgesteuert: 
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"
}
Antwort: 
{
  "client_id": "abc123",
  "client_secret": "secret456",
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"]
}
Speichern Sie das client_secret sicher — es kann später nicht mehr abgerufen werden.

​
Geltungsbereiche

GeltungsbereichZugriff
apiVoller Lese-/Schreibzugriff auf die Core- und Metadata-APIs
profileProfilinformationen des authentifizierten Benutzers lesen
Fordern Sie Geltungsbereiche als durch Leerzeichen getrennte Zeichenfolge an: scope=api profile

​
Autorisierungscode-Flow

Verwenden Sie diesen Flow, wenn Ihre App im Namen eines Twenty-Benutzers handelt.

​
1. Leiten Sie den Benutzer zur Autorisierung weiter

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
ParameterErforderlichBeschreibung
client_idJaIhre registrierte Client-ID
response_typeJaMuss code sein
redirect_uriJaMuss einer registrierten Redirect-URI entsprechen
scopeNeinDurch Leerzeichen getrennte Geltungsbereiche (Standard: api)
stateEmpfohlenZufällige Zeichenfolge zur Verhinderung von CSRF-Angriffen
code_challengeEmpfohlenPKCE-Challenge (SHA-256-Hash des Verifiers, base64url-codiert)
code_challenge_methodEmpfohlenMuss bei Verwendung von PKCE S256 sein
Der Benutzer sieht einen Zustimmungsbildschirm und stimmt dem Zugriff zu oder lehnt ihn ab.

​
2. Den Callback verarbeiten

Nach der Autorisierung leitet Twenty zurück zu Ihrer redirect_uri weiter: 
https://myapp.com/callback?code=AUTH_CODE&state=random_state_value
Überprüfen Sie, dass state mit dem übereinstimmt, was Sie gesendet haben.

​
3. Tauschen Sie den Code gegen Token aus

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

​
4. Verwenden Sie das Zugriffstoken

GET /rest/companies
Authorization: Bearer ACCESS_TOKEN

​
5. Aktualisieren, wenn abgelaufen

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

​
Client-Anmeldedaten-Flow

Für Server-zu-Server-Integrationen ohne Benutzerinteraktion: 
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
Das zurückgegebene Token hat Zugriff auf Arbeitsbereichsebene und ist an keinen bestimmten Benutzer gebunden.

​
Server-Ermittlung

Twenty veröffentlicht seine OAuth-Konfiguration an einem standardisierten Discovery-Endpunkt: 
GET /.well-known/oauth-authorization-server
Dies liefert alle Endpunkte, unterstützte Grant-Typen, Geltungsbereiche und Fähigkeiten — nützlich, um generische OAuth-Clients zu erstellen.

​
Zusammenfassung der API-Endpunkte

EndpunktZweck
/.well-known/oauth-authorization-serverErmittlung von Servermetadaten
/oauth/registerDynamische Client-Registrierung
/oauth/authorizeBenutzerautorisierung
/oauth/tokenToken-Austausch und -Aktualisierung
UmgebungBasis-URL
Cloudhttps://api.twenty.com
Selbsthostinghttps://{your-domain}

​
OAuth vs. API-Schlüssel

API-SchlüsselOAuth
EinrichtungIn den Einstellungen generierenClient registrieren, Flow implementieren
BenutzerkontextKeiner (Arbeitsbereichsebene)Berechtigungen eines bestimmten Benutzers
Am besten geeignet fürSkripte, interne ToolsExterne Apps, Multi-User-Integrationen
Token-RotationManuellAutomatisch über Refresh-Tokens
Geltungsbereichsbasierter ZugriffVoller API-ZugriffGranular über Geltungsbereiche