Verbinden Sie Ihre App mit Notiondesk über OAuth

OAuth ermöglicht es anderen Kunden von Notiondesk, Ihre App mit ihrem Workspace zu verbinden, ohne einen API-Schlüssel teilen zu müssen. Der Kunde meldet sich bei Notiondesk an, prüft die Anfragen Ihrer App und bestätigt sie. Ihre App erhält ein Zugriffstoken für die REST-API von Notiondesk, das der Kunde jederzeit widerrufen kann. Dieser Artikel beschreibt die Registrierung Ihrer App, die Ausführung des OAuth 2.0-Autorisierungscode-Flows mit PKCE, die Aktualisierung von Tokens und die Fehlerbehandlung.

Wann sollte man OAuth anstelle eines API-Schlüssels verwenden?

Jede Notiondesk API-Route akzeptiert beide Arten von Anmeldeinformationen und beantwortet sie auf die gleiche Weise: mit den gleichen Bereichen, Antworten und Fehlern.

Was Ihre App wissen muss

Lesen Sie die Endpunkte aus dem Metadatendokument des Autorisierungsservers, anstatt sie fest zu kodieren.

Führen Sie Ihren OAuth-Client auf einem Server aus. Browserbasierte Clients werden nicht unterstützt: Token-Austausch, Tokens und alle API-Aufrufe müssen auf Ihrem Backend verwaltet werden.

Schritt 1: Registrieren Sie Ihre App

Einmalige Registrierung mit dynamischer Kundenregistrierung :

Die Antwort 201 Created enthält Ihre client_id und, da Sie client_secret_post angefordert haben, auch eine client_secret. Das Geheimnis wird nur einmal angezeigt; speichern Sie es zusammen mit Ihren anderen Servergeheimnissen.

Mit "token_endpoint_auth_method": "none" ist Ihre App ein öffentlicher Client ohne Geheimnisse, und PKCE schützt den Codeaustausch.

Anstatt sich zu registrieren, können Sie die HTTPS-URL eines Client-Metadatendokuments als client_id verwenden. Notiondesk ruft das Dokument ab, sobald ein Kunde Ihre App autorisiert, und speichert es bis zu fünf Minuten lang im Cache.

Umleitungs-URI-Regeln

curl -X POST "https://api.notiondesk.so/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Acme Reports", "redirect_uris": ["https://acme.example/oauth/callback"], "token_endpoint_auth_method": "client_secret_post"}'

• Verwenden Sie https oder http auf einem Loopback-Host: 127.0.0.1, localhost oder [::1].

• Eine Loopback-Weiterleitung funktioniert auf jedem Port. Jede andere Weiterleitung muss exakt übereinstimmen.

• Platzhalter, Fragmente, Anmeldeinformationen vor dem Hostnamen (user@), Backslashes, Nicht-ASCII-Zeichen und prozentkodierte Hostnamen werden abgelehnt.

• Der Host, den ein Kunde auf dem Zustimmungsbildschirm sieht, stammt aus Ihren Redirect-URIs oder Ihrer client_id-URL. Registrieren Sie nur Hosts, die Ihnen gehören.

Schritt 2: Den Kunden an Notiondesk weiterleiten

Erstellen Sie eine zufällige code_verifier-Zahl und leiten Sie anschließend die code_challenge-Zahl als SHA-256-Hash des Prüfers ab, kodiert in base64url ( PKCE ). Leiten Sie den Browser des Kunden um zu:

https://api.notiondesk.so/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
  &scope=read%20write
  &state=RANDOM_STATE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.notiondesk.so

• resource ist erforderlich und muss exakt https://api.notiondesk.so entsprechen: Kleinbuchstaben, kein abschließender Schrägstrich, kein Pfad. Ein fehlender oder abweichender Wert beantwortet invalid_request.

• scope ist eine durch Leerzeichen getrennte Liste. Fragen Sie nur nach den Bereichen, die Ihre App verwendet.

• state schützt vor Cross-Site-Request-Forgery. Überprüfen Sie dies, wenn der Kunde zurückkehrt.

Ein für die Notiondesk REST-API ausgestelltes Token funktioniert nur mit der REST-API. Ein für Workspace MCP ausgestelltes Token wird von der REST-API abgelehnt, und umgekehrt.

Schritt 3: Der Kunde genehmigt Ihre App

Notiondesk zeigt den Zustimmungsbildschirm an. Der Kunde meldet sich an und sieht den Namen und Host Ihrer App, seinen Arbeitsbereich und die Berechtigungen Ihrer Anfrage, die seine Rolle zulässt. Er genehmigt oder lehnt die gesamte Anfrage ab.

Die Berechtigungen, die Ihre App erhalten kann, hängen von der Workspace-Rolle des Kunden ab:

Mit admin kann Ihre App das Branding des Hilfecenters ändern, Integrationen konfigurieren, deren Skripte im öffentlichen Hilfecenter geladen werden, und Weiterleitungen löschen. Fordern Sie diese Option nur an, wenn Ihre App diese Routen verwendet.

Der Kunde kann die Anfrage nicht genehmigen, wenn:

• Ihre Rolle erlaubt keinen der von Ihnen angeforderten Aufgabenbereiche;

• Ihr Arbeitsbereich verfügt nicht über API-Zugriff. Auf dem Zustimmungsbildschirm wird dann angezeigt: „Der Arbeitsbereichsplan beinhaltet keinen API-Zugriff.“ Für den API-Zugriff ist ein Enterprise-Plan erforderlich.

Nach der Genehmigung leitet der Browser Sie mit den Informationen code, Ihrem state und iss, der Kennung des Autorisierungsservers Notiondesk, zurück zu Ihrer Adresse redirect_uri. Verweigert der Kunde die Authentifizierung, wird stattdessen die Adresse error=access_denied weitergeleitet.

Schritt 4: Tausche den Code gegen Token ein

Der Code ist 60 Sekunden lang gültig und kann nur einmal verwendet werden:

Lassen Sie client_secret für einen öffentlichen Client weg. Die Antwort:

scope listet die vom Kunden gewährten Berechtigungen auf; diese können geringer sein als die von Ihnen angeforderten. Speichern Sie beide Token auf Ihrem Server.

Schritt 5: Rufen Sie die Notiondesk API auf.

Senden Sie das Zugriffstoken als Bearer-Token, genau wie einen API-Schlüssel:

Die Gültigkeitsbereiche des Tokens sind auf die aktuelle Rolle des genehmigenden Kunden beschränkt: Wenn ein Kunde zur Rolle „Viewer“ wechselt, bleibt Ihrer App nur noch der Bereich „read“ erhalten, und eine Route, die einen fehlenden Bereich benötigt, antwortet mit dem Fehlercode 403 „insufficient_scope“.

Ratenlimit-Budgets und Idempotency-Key-Werte gehören zur jeweiligen Berechtigung. Jede Genehmigung stellt eine neue Berechtigung mit eigenen Budgets und Schlüsseln dar, und eine Token-Aktualisierung erhält beides.

Schritt 6: Zugriffstoken aktualisieren

Ein Zugriffstoken ist eine Stunde gültig. Bevor es abläuft, tauschen Sie das Aktualisierungstoken gegen ein neues Paar ein:

Bei jeder Aktualisierung wird ein neues Aktualisierungstoken zurückgegeben, das 30 Tage gültig ist und das zuvor gesendete Token ungültig macht. Speichern Sie das neue Aktualisierungstoken, bevor Sie das neue Zugriffstoken verwenden.

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d redirect_uri=https://acme.example/oauth/callback

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8f3c...",
  "scope": "read write"
}

curl "https://api.notiondesk.so/sites" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "nd-version: 2026-10-16"

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=THE_REFRESH_TOKEN

Verwenden Sie niemals ein Refresh-Token wieder. Das Senden eines bereits verwendeten Tokens führt zum Widerruf der gesamten Berechtigung, einschließlich des Zugriffstokens, da die Wiederverwendung bedeutet, dass das Token kopiert wurde. Der Kunde muss Ihre App anschließend erneut autorisieren.

Wie Kunden Ihre App widerrufen

Workspace-Inhaber und Administratoren sehen alle Apps mit Zugriff auf ihren Workspace unter Einstellungen > Entwickler > Verbundene Apps . Apps, die die REST-API verwenden, zeigen die REST-API in der Spalte „ Zugriff“ an, zusammen mit der App, der Person, die sie autorisiert hat, ihren Berechtigungen und ihrer letzten Aktivität. Durch das Widerrufen der Berechtigung wird diese sofort beendet: Zugriffstoken und Aktualisierungstoken sind für die nächste Anfrage ungültig.

Eine Förderung endet auch von selbst:

• nach 30 Tagen ohne Aktualisierung;

• wenn sein Aktualisierungstoken wiederverwendet wird.

Solange der genehmigende Kunde nicht über die für eine Route erforderliche Rolle verfügt oder der Workspace-Plan keinen API-Zugriff besitzt, werden Anfragen abgelehnt. Sie funktionieren wieder, sobald die Rolle oder der Plan vor Ablauf der Berechtigung wiederhergestellt ist.

Fehlerbehebung bei Notiondesk OAuth

Die Autorisierungs- und Token-Endpunkte beantworten Standard-OAuth-Fehler, nicht den API-Fehlerumschlag Notiondesk:

{"error": "invalid_grant", "error_description": "Invalid authorization code."}

Der Autorisierungsendpunkt zeigt diese Fehler selbst an und leitet ungültige Anfragen niemals an Ihre redirect_uri weiter. Eine verweigerte Zustimmung erreicht Ihre App nur durch die error=access_denied-Weiterleitung.

API-Aufrufe selbst antworten mit dem API-Fehlercode Notiondesk . Ein abgelaufenes oder widerrufenes Zugriffstoken antwortet mit dem Statuscode 401 authentication_error und der Meldung „Ungültiger oder fehlender API-Schlüssel.“, der gleichen Meldung, die bei einem nicht verwendbaren API-Schlüssel ausgegeben wird.

Häufig gestellte Fragen

Was kommt als Nächstes?

• Legen Sie los mit der Notiondesk REST-API.

• Authentifizieren Sie sich mit der Notiondesk API mithilfe der API-Schlüssel.

• Workspace MCP-Zugriff trennen oder widerrufen