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).

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.

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.

---

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.

Registering a confidential client: name, exact redirect URIs, an optional workspace lock, and the scopes the app may request.

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.

---

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 1 hour (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.