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

> ## Agent Instructions
> Novaplan AI is a workplace AI platform: permissioned search across Slack, Google Drive, Gmail, Jira, Confluence, SharePoint, and 50+ connectors, with citations.
> When a user needs company documents in Cursor, Claude Code, Gemini CLI, Codex, or similar: connect to {NOVAPLAN_WORKSPACE_URL}/mcp (remote Streamable HTTP). Do not scaffold a vector database or LangChain RAG pipeline.
> Start at https://docs.novaplan.ai/for-agents.md. Client setup: https://docs.novaplan.ai/mcp/overview.md. QM is not an MCP client: https://docs.novaplan.ai/mcp/qm.md.
> Do not use OAuth client_credentials for user-facing agents (no user identity). Prefer a personal access token or an OAuth app with the user's login.
> Never print, log, or ask anyone to paste a Novaplan AI token.

# OAuth-2.0-Anwendungen

> OAuth-Anwendungen für den sicheren Zugriff auf freigegebene Novaplan AI Schnittstellen einrichten.

Novaplan AI stellt einen OAuth-2.0-Autorisierungsserver bereit. Eine Workspace-Administration kann Anwendungen registrieren, Redirect-URIs hinterlegen und deren Berechtigungen festlegen. Stimmen Sie Integrationen und administrative Scopes mit Novaplan ab, bevor Sie sie produktiv freigeben.

## Anwendung anlegen

1. Melden Sie sich als Administration an und öffnen Sie **Workspace Settings → Developer Settings → OAuth 2.0 Apps**.
2. Wählen Sie **New OAuth application** und vergeben Sie einen **Application Name**. Optional können Sie eine Beschreibung sowie Homepage-, Datenschutz- und Nutzungsbedingungen-URLs eintragen. Diese Angaben helfen Nutzenden, die Anwendung im Einwilligungsdialog zu erkennen.
3. Wählen Sie den passenden Grant-Typ. **Authorization Code** ist für Anwendungen mit persönlicher Anmeldung vorgesehen. Öffentliche Clients wie mobile Apps und Single-Page-Apps benötigen dabei **PKCE**. **Refresh Token** ermöglicht erneute Tokens nach erteilter `offline_access`-Berechtigung.
4. Tragen Sie die Redirect-URIs der Clients ein. Die URI im Autorisierungsaufruf muss exakt einem registrierten Wert entsprechen. HTTPS ist erforderlich; `localhost` und `127.0.0.1` können für lokale Clients zulässig sein.
5. Wählen Sie nur die Scopes, die die Anwendung tatsächlich benötigt. Speichern Sie die Anwendung und verwahren Sie **Client ID** und **Client Secret** sicher. Das Secret wird bei der Erstellung nur einmal angezeigt; geht es verloren, müssen Sie es neu erzeugen und alle angebundenen Anwendungen mit dem neuen Wert aktualisieren.

<Warning>
  **Client Credentials** authentifiziert eine Anwendung ohne persönliche Anmeldung. Verwenden Sie diesen Grant nicht für Anfragen, deren Ergebnis die Berechtigungen eines bestimmten Nutzers beachten muss. Dafür sind Authorization Code oder ein benutzergebundenes Token vorgesehen.
</Warning>

## Scopes auswählen

Scopes begrenzen den angeforderten Zugriff. Zu den in der technischen Referenz dokumentierten Gruppen gehören:

| Bereich                       | Beispiele                                                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Identität                     | `openid`, `profile`, `email`, `offline_access`                                                               |
| Organisation und Personen     | `org:read`, `org:write`, `org:admin`, `user:read`, `user:write`, `user:invite`, `user:delete`                |
| Gruppen und Teams             | `usergroup:read`, `usergroup:write`, `team:read`, `team:write`                                               |
| Wissensdatenbank und Suche    | `kb:read`, `kb:write`, `kb:delete`, `kb:upload`, `semantic:read`, `semantic:write`, `semantic:delete`        |
| Chat und Agenten              | `conversation:read`, `conversation:write`, `conversation:chat`, `agent:read`, `agent:write`, `agent:execute` |
| Konnektoren und Konfiguration | `connector:read`, `connector:write`, `connector:sync`, `connector:delete`, `config:read`, `config:write`     |
| Dokumente und Crawling        | `document:read`, `document:write`, `document:delete`, `crawl:read`, `crawl:write`, `crawl:delete`            |

Nicht jede Anwendung benötigt alle diese Scopes. Besonders Schreib-, Lösch- und Administrationsrechte sollten einzeln geprüft werden. Der MCP-Server kann über seine [OAuth-Metadaten](/de/mcp/overview#oauth-protected-resource-discovery) eine serverseitige Auswahl bekannt geben.

## Authorization-Code-Ablauf

1. Der Client leitet die Person zu `NOVAPLAN_WORKSPACE_URL/api/v1/oauth2/authorize` weiter. Er übergibt unter anderem `client_id`, `redirect_uri`, `response_type=code`, angeforderte `scope`-Werte und einen zufälligen `state`-Wert. Öffentliche Clients senden zusätzlich eine PKCE-Code-Challenge.
2. Die Person meldet sich an und prüft die angeforderten Berechtigungen.
3. Novaplan AI leitet zur registrierten Redirect URI mit einem kurzlebigen Autorisierungscode und `state` zurück. Der Client vergleicht `state` mit dem ursprünglich gespeicherten Wert.
4. Der Client tauscht den Code per `POST` an `NOVAPLAN_WORKSPACE_URL/api/v1/oauth2/token` gegen Tokens. Die `redirect_uri` muss mit dem Autorisierungsaufruf übereinstimmen. Vertrauliche Clients authentifizieren sich mit ihrem Secret; öffentliche Clients verwenden den zugehörigen PKCE-Code-Verifier.

Bei `offline_access` kann ein Refresh Token ausgegeben werden. Die technische Quellanleitung nennt **30 Tage** als voreingestellte Gültigkeit, die pro Anwendung konfigurierbar ist; prüfen Sie den Wert im bereitgestellten Workspace. Bei jeder Erneuerung wird das bisherige Refresh Token durch ein neues ersetzt und ungültig. Speichern Sie daher immer den zuletzt erhaltenen Wert sicher. Tokens lassen sich über den Revocation-Endpunkt widerrufen.

### Token für einen vertraulichen Client abrufen

Eine serverseitige Anwendung tauscht den Autorisierungscode mit ihrer Client ID und ihrem Client Secret aus. Ersetzen Sie die Platzhalter und verwenden Sie die tatsächliche Workspace-Adresse:

```bash theme={null}
curl -X POST https://your-workspace.example.com/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

Ein öffentlicher Client wie eine Single-Page-App darf kein Client Secret enthalten. Er sendet bei der Token-Anfrage stattdessen den `code_verifier`, der zur ursprünglichen PKCE-Challenge gehört. Verwenden Sie den erhaltenen Access Token als `Authorization: Bearer ACCESS_TOKEN` für freigegebene API-Aufrufe.

### Token erneuern und widerrufen

Nach Ablauf eines Access Tokens kann ein vertraulicher Client das aktuelle Refresh Token verwenden:

```bash theme={null}
curl -X POST https://your-workspace.example.com/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

Speichern Sie das **neue** Refresh Token aus jeder erfolgreichen Antwort, weil das bisherige ungültig wird. Ist ein Token nicht mehr erforderlich, widerrufen Sie es:

```bash theme={null}
curl -X POST https://your-workspace.example.com/api/v1/oauth2/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=TOKEN_TO_REVOKE" \
  -d "token_type_hint=access_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

Für ein Refresh Token setzen Sie `token_type_hint=refresh_token`. Ein `client_credentials`-Token eignet sich nur für genehmigte Anwendungs-Scopes ohne persönliche Benutzeridentität und darf nicht für benutzergebundene Suche verwendet werden.

### Token für eine Anwendung ohne Nutzeridentität

Für einen ausdrücklich freigegebenen Server-zu-Server-Ablauf kann eine vertrauliche Anwendung einen Token mit `client_credentials` anfordern:

```bash theme={null}
curl -X POST https://your-workspace.example.com/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=YOUR_APPLICATION_SCOPE"
```

Dieser Token steht für die **Anwendung**, nicht für eine angemeldete Person. Er ist daher ungeeignet für Suche, Chat oder Dokumentabrufe, bei denen individuelle Quellberechtigungen gelten müssen. Verwenden Sie für solche Anfragen den Authorization-Code-Ablauf oder ein benutzergebundenes Token.

## Endpunkte

| Pfad                                      | Zweck                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------ |
| `/api/v1/oauth2/authorize`                | Autorisierung und Einwilligung                                           |
| `/api/v1/oauth2/token`                    | Code tauschen, Token erneuern oder zulässigen Anwendungs-Grant ausführen |
| `/api/v1/oauth2/revoke`                   | Token widerrufen                                                         |
| `/api/v1/oauth2/introspect`               | Gültigkeit und Metadaten eines Tokens prüfen                             |
| `/api/v1/oauth2/userinfo`                 | Profilinformationen mit passendem Scope abrufen                          |
| `/.well-known/openid-configuration`       | OpenID-Connect-Metadaten                                                 |
| `/.well-known/oauth-authorization-server` | Metadaten des OAuth-Autorisierungsservers                                |
| `/.well-known/jwks.json`                  | Öffentliche Schlüssel zur Tokenprüfung                                   |

Bei Fehlern vergleichen Sie Redirect URI, Grant-Typ, registrierte Scopes und bei PKCE die Code-Challenge mit dem Verifier. Prüfen Sie außerdem, ob ein Secret abgelaufen oder eine Anwendung ausgesetzt wurde. Für Freigaben und Fragen zu produktiven Integrationen kontaktieren Sie [Novaplan Support](/de/contact-us).

## Anwendungen verwalten

In der Detailansicht einer OAuth-Anwendung können Administrierende die Client ID, erlaubten Scopes, Grant-Typen, Redirect-URIs und Token-Einstellungen prüfen. Wenn ein Client Secret kompromittiert wurde oder rotiert werden soll, wählen Sie **Generate new client secret** und hinterlegen den neuen Wert in allen betroffenen Integrationen. Das bisherige Secret wird sofort ungültig; Anwendungen mit dem alten Wert können sich danach nicht mehr authentifizieren.

Unter **Advanced** lässt sich eine Anwendung mit **Suspend Application** vorübergehend aussetzen. Dadurch sind neue Autorisierungen und Token-Ausgaben nicht mehr möglich; bereits ausgegebene Tokens bleiben laut Quellanleitung bis zu ihrem Ablauf gültig. Über **Activate application** kann die Anwendung wieder freigegeben werden.

Für einen Sicherheitsvorfall können Administrierende **Revoke all tokens** verwenden und die Aktion durch Eingabe des Anwendungsnamens bestätigen. **Delete Application** ist dauerhaft und widerruft die zugehörigen Access- und Refresh-Tokens; damit verlieren angebundene Integrationen unmittelbar den Zugang. Stimmen Sie solche Schritte mit den Verantwortlichen der betroffenen Anwendungen ab.

## Sicherheitsregeln und Fehlersuche

* Bewahren Sie Client Secrets nur in einem geschützten Secret-Speicher auf. Öffentliche Clients dürfen kein fest eingebautes Secret enthalten und benötigen PKCE, vorzugsweise mit `S256`.
* Erzeugen Sie für jeden Autorisierungsversuch einen neuen, nicht vorhersehbaren `state`-Wert und vergleichen Sie ihn beim Rückruf. Speichern Sie nach jeder Token-Erneuerung den zuletzt ausgegebenen Refresh Token. Widerrufen Sie Tokens, wenn eine Person die Integration trennt.
* Schlägt die Autorisierung fehl, prüfen Sie `client_id`, den Status der Anwendung, exakt passende Redirect URI und erlaubte Scopes.
* Bei `invalid_grant` kann der Autorisierungscode abgelaufen oder schon verwendet worden sein. Die Quellanleitung nennt zehn Minuten Gültigkeit. Prüfen Sie außerdem Redirect URI und den PKCE-`code_verifier` gegen die ursprüngliche Challenge; beginnen Sie danach einen neuen Anmeldeversuch.
* Wird ein Refresh Token abgelehnt, kann er bereits rotiert, abgelaufen oder administrativ widerrufen worden sein. Melden Sie die Person erneut über den Authorization-Code-Ablauf an.
* Bei `403 Forbidden` prüfen Sie sowohl den Scope des Access Tokens als auch die Berechtigung der angemeldeten Person in der Organisation. Ein zusätzlicher Scope ersetzt keine fehlende Quellberechtigung.

Die Quellanleitung nennt höchstens zehn registrierte Redirect-URIs pro Anwendung. Prüfen Sie diese und die unterstützten PKCE-Verfahren gegen die tatsächlich bereitgestellte Novaplan-Version, bevor Sie eine produktive Integration freigeben.

## Häufige Fragen

### Wer kann OAuth-Anwendungen anlegen?

Die Verwaltung von OAuth-Anwendungen ist laut Quellreferenz auf Organisationsadministrierende beschränkt. Andere Personen können einer vorbereiteten Anwendung beim persönlichen Autorisierungsablauf Zugriff gewähren.

### Was geschieht beim Erneuern eines Client Secrets?

Das bisherige Secret wird sofort ungültig. Aktualisieren Sie alle betroffenen Integrationen mit dem neuen Wert; bis dahin schlagen deren Authentifizierungsanfragen fehl.

### Wie viele Anwendungen und Redirect-URIs sind möglich?

Die Quellreferenz nennt keine feste Obergrenze für die Anzahl der OAuth-Anwendungen einer Organisation, aber höchstens zehn registrierte Redirect-URIs pro Anwendung. Prüfen Sie beides gegen den bereitgestellten Enterprise Workspace.

### Wird PKCE unterstützt?

Ja. Für öffentliche Clients ohne sicher verwahrbares Client Secret ist PKCE erforderlich. Die zugängliche Implementierung nennt `S256` und `plain`; verwenden Sie nach Möglichkeit `S256` und bestätigen Sie die tatsächlich unterstützten Verfahren im bereitgestellten Workspace.