OIDC client setup

To integrate an application with FlexGalaxy identity, register it as an OIDC client in DotID. DotID issues OAuth 2.0 / OpenID Connect tokens that your application can exchange for an authenticated session, and your service can validate those tokens against the issuing realm’s JWKS endpoint.

This page covers registration, client types, and the conventions DotID enforces.

Register your application as an OIDC client

There are two ways to register a client, depending on who you are.

Self-service (developer API)

External developers register applications through the developer self-service API:

POST /developer/v1/services

Submit a service registration manifest that declares your OIDC client(s) (see the external developer API example). A successful create returns 201 Created.

Default: public + PKCE (no secret). For native apps, mobile apps, SPAs, and CLIs, request a public client — the recommended shape for anything that runs on a user’s device or in a browser. Set:

{ "public_client": true, "pkce": "S256" }

DotID provisions a public client (token_endpoint_auth_method=none) and returns no client_secret — a public client authenticates only by proving possession of the PKCE code_verifier. Public clients are also stamped with two protocol mappers automatically:

  • an audience mapper (aud=flexgalaxy-api), so the issued access token is accepted by the FlexGalaxy.AI API surface, and

  • an account_id mapper, so the signed-in user’s tenant is resolvable from the token (see tenant binding claims).

Granted scopes are openid profile email.

For a server-side confidential client (which does hold a secret), see Confidential clients below. If you request a confidential client but declare a native (custom-scheme) or loopback redirect URI, the request is rejected with 400 — DotID will not silently downgrade it to a secret- bearing client. Use a public client for those redirects instead.

You can retrieve or rotate credentials later:

GET  /developer/v1/services/{serviceId}/credentials
POST /developer/v1/services/{serviceId}/credentials:rotate

Console (first-party / admin)

Platform operators register first-party clients through the admin console:

  1. Sign in to {{ dotid_admin_console_prod_stargate }} with platform admin credentials.

  2. Open the Applications section and choose Register OIDC client.

  3. Fill in:

    • Client ID — a short, stable identifier (lower-kebab-case). This becomes the value of the client_id parameter in OAuth requests.

    • Display name — what users see on the consent screen.

    • Realm — which realm hosts the client (see Realms and which to register against below).

    • Client type — confidential or public.

    • Redirect URIs — exact-match URIs the client may receive auth codes at.

    • Allowed scopes — typically openid profile email plus any custom scope your service needs.

  4. On save, DotID returns the client ID and (for confidential clients) the client secret. Store the secret in your service’s secret manager — it is shown once.

Account administrators register account-scoped clients through their account-administration console, which forwards to the same backend with the account realm preselected.

Client types

DotID supports the two standard OAuth 2.0 client types. Prefer a public + PKCE client for anything that runs on a user’s device or in a browser.

Public clients

A public client cannot keep a secret (browser SPAs, mobile apps, native apps, CLIs). It authenticates only by proving possession of the original PKCE code verifier — DotID returns no client_secret. Request it with:

  • public_client: true

  • pkce: S256

DotID rejects authorization-code exchanges from public clients that do not include a PKCE verifier. Public clients registered through the developer API are stamped with the aud (flexgalaxy-api) and account_id protocol mappers automatically, and are granted openid profile email.

Confidential clients

A confidential client runs server-side and can keep a secret. It authenticates to the token endpoint using its client_secret (or, for stricter setups, a private-key JWT). Use confidential clients for:

  • Backend services that exchange authorization codes server-side.

  • Service-to-service calls that use the client credentials grant.

  • Any flow where the client process is not exposed to end users.

The client_secret is returned once, on create — store it in your service’s secret manager immediately.

A confidential client may not declare a native (custom-scheme) or loopback redirect URI. Such a request is rejected with 400 rather than downgraded to a secret-bearing client — register those redirects on a public client instead.

Recommended baseline for server-side apps: confidential client + Authorization Code grant + PKCE with S256. The combination of a client secret and PKCE protects against both client-impersonation and code-interception attacks.

Realms and which to register against

DotID is multi-realm. Which realm hosts your client determines which users can sign in to it and which APIs trust the tokens it issues.

  • Platform-wide clients — register against the flexgalaxy realm. These are clients that any FlexGalaxy.AI user (across accounts) may sign in to.

  • Account clients — register against the per-account realm acc-<account-id>. These accept only users who belong to that specific account.

  • Identity Center clients — register against idc-<account-id>-<region>. These integrate with the account’s Identity Center for permission-set assumption flows.

  • Platform-administration clients — register against the flexgalaxy realm.

See API authentication and JWT validation for which tokens your service should accept.

Redirect URIs

DotID enforces exact-match redirect URIs. A registered URI of https://app.example.com/oauth2/callback does not match https://app.example.com/oauth2/callback/ (note the trailing slash) or https://app.example.com/oauth2/callback?foo=bar (extra query). Register every URI variant your application actually uses.

Redirect trust is tiered by the kind of URI:

Redirect kind

Example

Trust

Native custom-scheme

com.example.app://callback

Public client only. Auto-trusted.

Loopback

http://127.0.0.1:<port>/callback, http://localhost:<port>/callback

Public client only. Auto-trusted (any port, exact path).

Production https://

https://app.example.com/oauth2/callback

For a public client, only trusted when the host is proven via verified_domains. Confidential clients keep the standard server-side https behavior.

For a public client with a production https:// redirect, include the redirect host in the manifest’s verified_domains (App Links / Universal Links domain proof):

{
  "public_client": true,
  "pkce": "S256",
  "redirect_uris": ["https://app.example.com/oauth2/callback"],
  "verified_domains": ["app.example.com"]
}

An https redirect whose host is not in verified_domains is rejected — this proves the app controls the domain before DotID will send auth codes there.

Rules:

  • HTTPS is required for all production redirect URIs. Loopback http:// is permitted for native/CLI flows; other non-loopback http:// is rejected.

  • Wildcards are not allowed in redirect URIs.

  • Fragments (#…) are not allowed in redirect URIs.

  • The conventional callback path is /oauth2/callback. Stick to the convention unless you have a reason not to.

Scopes you can request

Scope

Effect

openid

Required for OIDC. Issues an ID token.

profile

Adds name, preferred_username, and other profile claims to the ID token.

email

Adds email and email_verified claims.

groups

Adds a groups array claim listing the user’s group memberships.

offline_access

Issues a refresh token. Required for long-running background processes.

Custom scopes (e.g. dotid:audit:read) can be defined per realm by platform operators. Request only the scopes your service genuinely needs — over-broad scope requests are flagged on the consent screen and erode user trust.

See API authentication and JWT validation for how to validate the tokens these scopes produce.