# Client settings

> See every setting an administrator can set on a OneiD client, what each one controls and the rules OneiD applies to it.

Source: https://oltinid.com/docs/reference/client-settings/ · Section: Reference · All OneiD documentation: https://oltinid.com/llms.txt

Every application that signs users in or calls the token endpoint is registered in OneiD as a client. An administrator creates and changes clients in the admin console or through the [Admin API](https://oltinid.com/docs/operate/admin-api/). There is no dynamic client registration. This page lists every client setting, so that developers know what to ask for and administrators know what each setting does.

## Settings

| Setting | Values | Default | What it controls |
|---|---|---|---|
| Client ID | Text | Set by the administrator | The identifier your application sends as `client_id`. It appears as `aud` in ID tokens and `client_id` in access tokens. |
| Display name | Text | Set by the administrator | A readable name for the application. In client credentials access tokens it is the `name` claim. |
| Client type | `public` or `confidential` | Set by the administrator | `public` for browser, mobile and desktop applications, which cannot keep a secret. `confidential` for server-side applications and services, which hold a client secret. |
| Grant types | `authorization_code`, `refresh_token`, `client_credentials` | Set by the administrator | Which grants the client may use. `client_credentials` is for confidential clients only. |
| PKCE required | On or off | On | Whether the client must send a PKCE code challenge. Always on for public clients. An administrator can turn it off for a confidential client; keep it on. |
| Redirect URIs | List of URIs | None | Where OneiD may send the authorisation response. See [redirect URI rules](#redirect-uri-rules). |
| Post-logout redirect URIs | List of URIs | None | Where OneiD may send the browser after sign-out. Must match exactly; the [redirect URI rules](#redirect-uri-rules) apply. |
| Allowed scopes | Identity scopes and API scopes | Set by the administrator | The scopes the client may request. A request for any other scope gets `invalid_scope`. |
| Allowed CORS origins | List of origins | None | Browser origins that may call the token, userinfo and revocation endpoints cross-origin. See [CORS origins](#cors-origins). |
| Consent required | On or off | Set by the administrator | Whether users see a consent page for this client. See [consent](#consent). |
| Access token lifetime | Duration | 1 hour | How long access tokens for this client are valid. |
| ID token lifetime | Duration | 20 minutes | How long ID tokens for this client are valid. |
| Refresh token lifetime | Duration | 14 days | How long a refresh token chain lasts. Refreshes do not extend it. |
| Enabled | Enabled or disabled | Set by the administrator | A disabled client cannot sign users in or get tokens. |
| Client secret | One secret, optional expiry | Confidential clients only | How a confidential client authenticates. See [client secret](#client-secret). |

The authorization code lifetime (5 minutes) is fixed and cannot be changed per client.

## Notes

### Client type and PKCE

- A public client has no secret. PKCE with `S256` is always required.
- A confidential client has one client secret. PKCE is required by default. Keep it on: it protects the authorization code even for server-side applications.

### Grant types

- `authorization_code`: user sign-in. The client needs the redirect URIs your application uses.
- `refresh_token`: lets the client exchange refresh tokens. The client also has to request `offline_access` to receive one, so `offline_access` must be among its allowed scopes.
- `client_credentials`: a service acting for itself, with no user. Confidential clients only.

### Redirect URI rules

- OneiD compares redirect URIs exactly. There are no wildcards.
- `https` is required, except `http` on loopback addresses: `localhost`, `127.0.0.1` and `[::1]`.
- Private-use schemes in reverse-domain form, such as `com.example.app:/callback`, are allowed for public clients only.
- A redirect URI must not contain a fragment (`#...`).

### Allowed scopes

- Identity scopes: `openid`, `profile`, `email`, `phone`, `roles`, `offline_access`. There is no `address` scope.
- API scopes are created by an administrator, for example `orders.read`. None exist by default.
- The privileged scopes `admin_api`, `admin_api_readonly` and `admin_console_webhooks` are for OneiD's own administration. Only a full administrator (role `All`) can allow them for a client, and they are removed at sign-in for users without an administrator role. Do not use them in applications.

### CORS origins

- Enter each origin as `scheme://host[:port]`, without a path, for example `https://app.example.com`.
- Origins take effect only on an enabled client. Changes take effect within about 15 seconds.
- Introspection never allows cross-origin requests. Discovery and JWKS answer any origin without registration.
- CORS requests never carry OneiD cookies.

### Consent

- **Consent required (explicit):** users see a consent page for the scopes the client requests. If the user ticks "remember", OneiD keeps the decision and does not ask again for the same set of scopes. Users can untick optional scopes. A refusal returns `access_denied`.
- **Consent not required (implicit):** typical for first-party applications. No consent page is shown, unless the request carries `prompt=consent`.

### Enabled and disabled

When a client is disabled:

- the authorize and logout endpoints answer `unauthorized_client`,
- the token, introspection and revocation endpoints answer `invalid_client`,
- OneiD revokes the client's tokens.

### Client secret

- A confidential client has exactly one client secret.
- When OneiD generates the secret, the value is shown once. Copy it into your application's secret store straight away; it cannot be displayed again.
- An administrator can supply a secret instead. It must be at least 32 characters long.
- A secret can have an optional expiry. After it, the token endpoint answers `invalid_client` with "The client secret has expired."
- Replacing a secret takes effect immediately: the old secret stops working at once. Plan the change: have the new value ready to deploy to your application when the administrator replaces it.
- Disabling the secret disables the client and revokes its tokens.
- Your application sends the secret with `client_secret_basic` (recommended) or `client_secret_post`. Never put a secret in a browser, mobile or desktop application.

> **Note:** `private_key_jwt` and mutual TLS client authentication are not available. There is no setting for a client public key or certificate.

## Endpoint permissions

OneiD derives each client's endpoint permissions from its grant types and client type. Administrators do not set them.

| Endpoint | Allowed when |
|---|---|
| Token | Always |
| Revocation | Always |
| Authorize | The client has the `authorization_code` grant |
| End session (logout) | The client has the `authorization_code` grant |
| Introspection | The client is confidential |

## Learn more

- [Register an application](https://oltinid.com/docs/get-started/register-an-application/)
- [Choose a flow](https://oltinid.com/docs/get-started/choose-a-flow/)
- [Browser applications and CORS](https://oltinid.com/docs/guides/browser-applications/)
- [Automate with the Admin API](https://oltinid.com/docs/operate/admin-api/)