> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/api-access/oauth-apps.md).

# OAuth Apps

If you are building a third-party application that authenticates users against RootCause, register it as a **confidential OAuth client** on the **API** page, in the **OAuth Apps** section (see [API Access](/api-and-integrations/api-access.md)).

Each registered app receives a **client ID** and a **one-time client secret**. The secret is shown once at registration: store it securely, because it cannot be retrieved later.

{% hint style="info" %}
Public MCP clients (Claude Code, Claude Desktop, Cursor, and similar) register themselves automatically through the OAuth flow and are **not** listed here — the connections you have personally authorized appear in the **Connected Apps** section of the API page instead, where they can be revoked. This section is only for confidential clients you build and operate yourself.
{% endhint %}

***

## Registering an app

In **Register new app**, fill in:

* **App name** — the name users see on the consent screen, for example "Acme Analytics".
* **Redirect URIs** — one per line. These must match **exactly** at authorization time; a mismatch rejects the request.
* **Workspace lock** *(optional)* — pin the app to a single workspace. The default is org-wide, where the user picks the workspace at consent time.
* **Allowed scopes** — restrict which permission areas the app may request: Sources, Datasets, Ontology, Digital Twins, Simulations, Connectors, Catalog, Jobs, Exports, Agent, and Reports. Leave empty to allow all.

<figure><img src="/files/9QCtjMLQ24Ozl7vVhrgY" alt="The OAuth Apps section of the API page with the Register new app form filled in: app name Acme Analytics, one redirect URI, workspace lock set to org-wide, and the eleven allowed-scope pills, above a Register app button"><figcaption><p>Registering a confidential client: name, exact redirect URIs, an optional workspace lock, and the scopes the app may request.</p></figcaption></figure>

Click **Register app** to receive the client ID and secret.

***

## How access works

Your app sends users through the standard OAuth authorization flow against your platform domain. At consent, the user sees the app name and requested scopes, picks the workspace (unless the app is workspace-locked), and approves. Tokens issued to the app are limited to the approved scopes and workspace.

The API surface available to an OAuth app is the same REST API documented in the [Interactive API Reference](/api-and-integrations/api-access.md#api-reference).

***

## Endpoints and protocol details

The authorization server publishes its metadata at `/.well-known/oauth-authorization-server`, which is the authoritative source. The endpoints:

| Endpoint                    | Path                |
| --------------------------- | ------------------- |
| Authorization               | `/oauth/authorize`  |
| Token                       | `/oauth/token`      |
| Dynamic client registration | `/oauth/register`   |
| Revocation                  | `/oauth/revoke`     |
| Introspection               | `/oauth/introspect` |

Protocol facts your implementation needs:

* **Grant types:** `authorization_code`, `refresh_token`, and `client_credentials`. Client credentials is only available to confidential clients bound to an organization.
* **PKCE is mandatory** on every authorization-code exchange, confidential clients included, and only the `S256` challenge method is accepted.
* **Redirect URIs are matched by exact string equality.** No wildcards, no prefix matching.
* **Access tokens** are JWTs valid for **15 minutes** (configurable per deployment). **Refresh tokens** last **30 days** and rotate on every use: each refresh invalidates the old token and issues a new one. A scope can be narrowed, never widened, at refresh time.
* **Client authentication** for confidential clients is `client_secret_basic` or `client_secret_post`.

Consent is remembered: once a user has approved an app for a given scope set, later authorizations with the same or narrower scopes auto-approve.