Register an application

Every application that uses OneiD is registered as a client by an administrator, in the admin console or through the Admin API. Developers cannot register clients themselves. This page describes the settings your administrator fills in, the rules your URIs must follow, and a template you can send them.

What the administrator enters

Warning The administrator sees the client secret only once, when it is created. Ask them to pass it to you through a secure channel, not by email or chat. If it is lost, the administrator must issue a new one.

Default token lifetimes

If the administrator leaves the lifetimes unchanged, OneiD uses these by default:

Consent

When consent is asked, OneiD shows a consent page the first time a user signs in to your application with a given set of scopes. The user can untick optional scopes, and OneiD remembers the decision if the user ticks “remember”. If the user refuses, your application receives access_denied.

When consent is not asked, OneiD shows the consent page only if your application sends prompt=consent.

Allowed scopes

Request only what you need. Identity scopes are openid, profile, email, phone, roles and offline_access. API scopes, such as orders.read, exist only after an administrator creates them. If your application requests a scope that the client is not allowed, OneiD returns invalid_scope.

Do not ask for admin_api, admin_api_readonly or admin_console_webhooks. These scopes are for administering OneiD itself and are not for applications.

URI rules

OneiD compares redirect URIs character by character. Your application must send exactly a registered value.

• Exact match. No wildcards, no prefix matching. https://app.example.com/callback and https://app.example.com/callback/ are different URIs.
• https. Every redirect URI uses https, except loopback addresses.
• http only for loopback. http://localhost, http://127.0.0.1 and http://[::1], for development and for desktop applications. The port is part of the URI and must match too.
• Private-use schemes for public clients only. Mobile and desktop apps may use a reverse-domain scheme, such as com.example.app:/callback.
• No fragments. A redirect URI cannot contain #.

Post-logout redirect URIs follow the same exact-match rule.

Allowed CORS origins are written as scheme://host[:port], with no path and no trailing slash, for example https://app.example.com or http://localhost:4200. After the administrator saves a change, it takes effect within about 15 seconds.

Tip Register one redirect URI for each environment, such as local development, test and production, rather than reusing one value. If you need separate settings per environment, ask for separate clients.

If your application sends a redirect_uri that is not registered, or a client_id that OneiD does not know, OneiD does not redirect back. It shows its own error page with invalid_request. See Errors and troubleshooting.

Request to your administrator

Copy this template, fill it in, and send it to your OneiD administrator.

Please register a OneiD client for this application.

Application name (shown to users):  Orders
Suggested client ID:                orders-web
Client type:                        confidential | public
Grant types:                        authorization_code
                                    refresh_token (only if we request offline_access)
                                    client_credentials (services only, confidential only)

Redirect URIs (exact):
  https://app.example.com/callback
  http://localhost:3000/callback

Post-logout redirect URIs (exact):
  https://app.example.com/signed-out
  http://localhost:3000/signed-out

Scopes we need:
  openid profile email
  offline_access (only with the refresh_token grant)
  API scopes: orders.read orders.write

Allowed CORS origins (browser applications only):
  https://app.example.com
  http://localhost:3000

Consent:          ask users | do not ask (first-party application)
PKCE:             required (keep the default)
Token lifetimes:  defaults

For confidential clients: please send the client secret through
our secret store, not by email or chat.

Once the client is registered, you receive the client ID, and for a confidential client the client secret. Your OneiD address is the base URL that your application uses as its authority, https://YOUR_ONEID.

Checkpoint Open https://YOUR_ONEID/.well-known/openid-configuration in a browser. You see the discovery document, and its issuer is https://YOUR_ONEID/.

When a client is disabled

An administrator can disable a client. A disabled client gets unauthorized_client at the authorize and end session endpoints and invalid_client at the other endpoints, and its tokens are revoked. If a client secret has expired, the token endpoint returns invalid_client with the description “The client secret has expired.” Ask your administrator for a new secret.

For every setting and its effect, see Client settings.

Learn more

• Client settings
• Choose a flow
• Scopes, claims and roles
• Browser applications and CORS