# Register an application

> Know what your OneiD administrator enters when registering your application, and send them the values they need.

Source: https://oltinid.com/docs/get-started/register-an-application/ · Section: Get started · All OneiD documentation: https://oltinid.com/llms.txt

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

| Setting | What it is | What you decide |
|---|---|---|
| Client ID | The identifier your application sends as `client_id`. | Suggest a short, readable value, for example `orders-web`. |
| Display name | The application's display name. For client credentials, it is also the `name` claim in the access token. | The name your users recognise. |
| Client type | `public` or `confidential`. | `public` for browser, mobile and desktop apps. `confidential` for server-side applications and services. |
| Grant types | Authorization code, refresh token, client credentials. | See [Choose a flow](https://oltinid.com/docs/get-started/choose-a-flow/). Public clients cannot have client credentials. |
| Redirect URIs | Where OneiD may send the user back after sign-in. | Every callback URL, for every environment. |
| Post-logout redirect URIs | Where OneiD may send the user after sign-out. | The pages your application shows after sign-out. |
| Allowed scopes | The scopes the client may request. | `openid` and the identity and API scopes you need. |
| Allowed CORS origins | Origins whose browsers may call the token, userinfo and revocation endpoints. | Browser applications only: the origin your app is served from. |
| PKCE | Whether PKCE is required. | Always required for public clients. Required by default for confidential clients; keep it on. |
| Consent | Whether users are asked to agree before the first sign-in. | Usually not asked for your own applications, asked for third-party ones. |
| Token lifetimes | Access token, ID token and refresh token lifetimes for this client. | Leave the defaults unless you have a reason. |
| Client secret | Confidential clients only. One secret per client. | Store it in a secret store, never in source code. |

> **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:

| Token | Default lifetime |
|---|---|
| Authorisation code | 5 minutes (cannot be changed) |
| Access token | 1 hour |
| ID token | 20 minutes |
| Refresh token | 14 days |

### 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](https://oltinid.com/docs/reference/errors/).

## Request to your administrator

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

```text
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](https://oltinid.com/docs/reference/client-settings/).

## Learn more

- [Client settings](https://oltinid.com/docs/reference/client-settings/)
- [Choose a flow](https://oltinid.com/docs/get-started/choose-a-flow/)
- [Scopes, claims and roles](https://oltinid.com/docs/guides/scopes-claims-roles/)
- [Browser applications and CORS](https://oltinid.com/docs/guides/browser-applications/)