OAuth 2.0 für Anwendungen

OAuth 2.0 ermöglicht einer Anwendung, im Namen eines Benutzers auf Planfix zuzugreifen, ohne das Passwort des Benutzers anzufordern oder zu speichern.

Planfix verwendet den Authorization Code-Flow mit obligatorischem PKCE S256. OAuth kann verwendet werden, um eine Verbindung zum REST API oder zum Planfix MCP-Server herzustellen.

Wenn Sie einen fertigen AI-Client anbinden möchten, beginnen Sie mit Planfix MCP. Wenn Sie den Zugriff in Ihrem Konto verwalten, siehe OAuth- und MCP-Anwendungen in einem Konto. Partner und Entwickler von Multi-Konto-Integrationen sollten OAuth-Anwendungen für Partner beachten.

Optionen zur Anwendungsregistrierung

Option	Wann verwenden	Wo es funktioniert
Konto-eigene Anwendung	Die Integration ist für ein einzelnes Konto vorgesehen und der Client benötigt eine vordefinierte client_id.	Nur im Konto, das sie besitzt.
Partner-eigene Anwendung	Dieselbe Anwendung muss sich mit mehreren Kundenkonten verbinden.	In Konten, in denen dies durch die Sicherheitsrichtlinie oder einen Administrator erlaubt ist.
Automatische MCP-Client-Registrierung	Der MCP-Client unterstützt ein Client ID Metadata Document (CIMD) oder Dynamic Client Registration (DCR).	Die Registrierung gewährt nicht automatisch Zugriff auf ein Konto. Die Anwendung muss im ausgewählten Konto weiterhin erlaubt sein.

CIMD und DCR sind nur für MCP-Verbindungen verfügbar. Für die REST API verwenden Sie eine konto-eigene oder partner-eigene Anwendung.

OAuth-Endpunkte

Neue Integrationen sollten die globalen Endpunkte verwenden. Der Kontoname ist in diesen URLs nicht enthalten: der Benutzer wählt während der Autorisierung ein Konto aus.

Zweck	Adresse
Issuer	https://auth.planfix.com
Authorization	https://auth.planfix.com/oauth/authorize
Token	https://auth.planfix.com/oauth/token
User information	https://auth.planfix.com/oauth/userinfo
Token revocation	https://auth.planfix.com/oauth/revoke
Dynamic MCP client registration	https://auth.planfix.com/oauth/register

Die Metadaten des Authorization Servers sind unter den Standardendpunkten verfügbar:

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

Redirect-URIs

Eine Redirect-URI muss in den Anwendungseinstellungen registriert sein. Der in einer Autorisierungsanfrage gesendete Wert muss mit einer registrierten URI übereinstimmen.

Erlaubt sind:

• https-URLs;
• http-URLs nur für Loopback-Hosts wie localhost oder 127.0.0.1.

Der Port darf für eine Loopback-URI dynamisch sein, aber Schema, Host, Pfad und Query müssen übereinstimmen. URL-Fragmente und Benutzerinformationen in der URL sind nicht erlaubt.

Zugriffsebenen

Eine Anwendung erhält nur die Zugriffsebenen bzw. scopes, die im Voraus erlaubt wurden. Siehe REST API access levels für die vollständige Liste.

Die angeforderte Menge muss eine Teilmenge der für die Anwendung registrierten Scopes sein. Anwendungsscopess erweitern nicht die Berechtigungen des Benutzers in Planfix: die Anwendung kann nur auf Daten zugreifen, die für die Mitarbeiterin bzw. den Mitarbeiter, die/der sie verbunden hat, verfügbar sind.

Verwaltete Anwendungen erhalten zusätzlich die Service-Scopes userinfo, openid und email.

Benutzerautorisierung

Erzeugen Sie ein code_verifier und dessen SHA-256-Darstellung, code_challenge, und öffnen Sie dann den Authorization-Endpunkt im Browser.

REST API-Beispiel:

GET https://auth.planfix.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &scope=openid%20email%20task_readonly
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

Für MCP fügen Sie den Parameter resource mit der exakten MCP-Server-URL hinzu:

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp

Parameter	Beschreibung
client_id	Die Kennung einer registrierten Anwendung. Für CIMD ist dies die URL des Client-Metadatendokuments.
redirect_uri	Eine der erlaubten Redirect-URIs.
response_type	Muss code sein.
scope	Die erforderlichen Berechtigungen, durch Leerzeichen getrennt. Dieser Parameter ist für die REST API verpflichtend. Ein MCP-Client kann ihn weglassen; in diesem Fall werden die für die Anwendung erlaubten Scopes verwendet.
state	Ein Zufallswert, der die Anfrage vor Vertauschung schützt. Die Anwendung muss ihn nach dem Redirect validieren.
code_challenge	Base64url ohne Padding des SHA-256-Hashes des code_verifier.
code_challenge_method	Nur S256 wird unterstützt.
resource	Für MCP die exakte URL https://mcp.planfix.com/mcp. Senden Sie diesen Parameter nicht für die REST API.

Der Benutzer wählt ein Konto aus, meldet sich an und prüft die angeforderten Berechtigungen. Eine konto-eigene Anwendung öffnet direkt ihr Eigentümerkonto. Wenn die Sicherheitsrichtlinie eine Administratorgenehmigung erfordert, zeigt Planfix den entsprechenden Schritt an. Ein Administrator kann die Anwendung genehmigen und in einem Schritt verbinden.

Nach erfolgreicher Autorisierung leitet Planfix den Browser zu redirect_uri weiter:

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Ein Authorization Code ist einmalig verwendbar und bleibt 10 Minuten gültig.

Tokens erhalten

Senden Sie eine POST-Anfrage an /oauth/token mit application/x-www-form-urlencoded:

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_verifier=CODE_VERIFIER

Für MCP wiederholen Sie den Parameter resource mit demselben Wert, der in der Autorisierungsanfrage verwendet wurde.

Ein Public Client sendet die Anfrage ohne Secret. Ein Confidential Client authentisiert sich zusätzlich mit client_secret_basic oder den Parametern client_id und client_secret im Request-Body.

Beispielantwort:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

Für die REST API enthält die Antwort außerdem account_name, account_domain und account_url. Speichern Sie diese Werte und verwenden Sie die URL des ausgewählten Kontos für REST-API-Anfragen.

Ein Access-Token ist 24 Stunden gültig. Es ist an Benutzer, Konto, Anwendung, Scopes und Resource gebunden. Ein für MCP ausgestelltes Token kann nicht direkt mit der REST API verwendet werden, und ein REST-API-Token nicht mit MCP.

Verwendung eines Tokens mit der REST API

Senden Sie das Token im Authorization-Header:

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Verwenden Sie die Konto-URL, die beim Austausch des Authorization Codes gegen Tokens zurückgegeben wurde. Es sind nur Methoden verfügbar, die durch die gewährten Scopes abgedeckt sind. OAuth-Tokens unterliegen dem Kontotarif und den Standard-REST API limits.

Benutzerinformationen

Die userinfo-Anfrage erfordert den Scope openid:

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Beispielantwort, wenn der Scope email vorhanden ist:

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

Globale OAuth-Autorisierung steht Konto-Mitarbeiter/innen zur Verfügung. Planfix stellt kein id_token aus; fordern Sie Benutzerdaten stattdessen über userinfo an.

Tokens auffrischen

POST https://auth.planfix.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&refresh_token=REFRESH_TOKEN

Für MCP senden Sie erneut dasselbe resource. Ein Confidential Client muss sich mit seinem Secret authentifizieren.

Planfix gibt ein neues Access-Token und ein neues Refresh-Token zurück. Das vorherige Refresh-Token wird sofort ungültig, daher muss die Anwendung den gespeicherten Wert atomar ersetzen.

Ein Token widerrufen

Ein Client kann ein Refresh-Token über /oauth/revoke widerrufen:

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Ein Benutzer kann eine Verbindung auch über den Bereich Session management in seiner Benutzerkarte entfernen. Ein Administrator kann die Genehmigung einer Drittanbieter-Anwendung für das gesamte Konto widerrufen. Siehe OAuth- und MCP-Anwendungen in einem Konto.

Kompatibilität mit bestehenden Integrationen

Tenant-Endpunkte wie https://account.planfix.com/api/v2/oauth/authorize, /token und /userinfo funktionieren weiterhin für bestehende Integrationen, die an ein bestimmtes Konto gebunden sind.

Verwenden Sie für neue Integrationen die globalen Endpunkte. Sie unterstützen standardmäßige Metadaten-Discovery, Kontenauswahl und MCP. Mischen Sie nicht globale und Tenant-Endpunkte innerhalb einer OAuth-Session.

Sicherheitsempfehlungen

• Verwenden Sie stets PKCE S256 und validieren Sie state.
• Verwenden Sie einen Public Client ohne Secret für mobile, Desktop- und Browser-Anwendungen.
• Verwenden Sie einen Confidential Client nur dann, wenn das Secret sicher auf einem Server gespeichert werden kann.
• Fordern Sie nur die minimal erforderliche Menge an Scopes an.
• Schreiben Sie Access-Tokens, Refresh-Tokens, Authorization Codes, code_verifier oder Client-Secrets nicht in Logs.
• Speichern Sie Refresh-Tokens und Client-Secrets in verschlüsseltem Speicher.
• Validieren Sie iss in der Antwort und akzeptieren Sie nur den erwarteten Planfix-Issuer.

Mögliche Fehler

Fehler	Ursache
invalid_client	Der Client ist unbekannt oder deaktiviert, das Client-Secret ist falsch oder die Anwendung ist im ausgewählten Konto nicht verfügbar.
invalid_grant	Der Authorization Code oder das Refresh-Token ist ungültig, abgelaufen, bereits verwendet oder stimmt nicht mit dem Client, der Redirect-URI, den PKCE-Daten oder der Resource überein.
invalid_scope	Die Anfrage enthält einen Scope, der für die Anwendung nicht erlaubt ist.
invalid_target	Die resource wird nicht unterstützt oder hat sich zwischen den Anfragen geändert.
access_denied	Der Benutzer hat die Verbindung abgelehnt oder die Kontorichtlinie erlaubt die Anwendung nicht.
HTTP 401, invalid_token	Das Access-Token ist unbekannt, abgelaufen oder widerrufen.
HTTP 403, insufficient_scope	Das Token enthält nicht den für die Operation erforderlichen Scope.

Gehe zu

• Planfix MCP
• OAuth- und MCP-Anwendungen in einem Konto
• OAuth-Anwendungen für Partner
• REST API
• REST API Authorization
• REST API: Access Levels List – scope