# Discovery document

> Read OneiD's OpenID Connect discovery document field by field and know which advertised options to use.

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

OneiD publishes an OpenID Connect discovery document at `https://YOUR_ONEID/.well-known/openid-configuration`. Point your library at your OneiD address and it reads the endpoints, keys and supported features from this document. This page explains each field and the few values you should not rely on.

## The document

```http
GET /.well-known/openid-configuration HTTP/1.1
Host: YOUR_ONEID
```

```json
{
  "issuer": "https://YOUR_ONEID/",
  "authorization_endpoint": "https://YOUR_ONEID/connect/authorize",
  "token_endpoint": "https://YOUR_ONEID/connect/token",
  "introspection_endpoint": "https://YOUR_ONEID/connect/introspect",
  "end_session_endpoint": "https://YOUR_ONEID/connect/logout",
  "revocation_endpoint": "https://YOUR_ONEID/connect/revoke",
  "userinfo_endpoint": "https://YOUR_ONEID/connect/userinfo",
  "jwks_uri": "https://YOUR_ONEID/.well-known/jwks",
  "grant_types_supported": ["authorization_code", "client_credentials", "refresh_token"],
  "response_types_supported": ["code"],
  "response_modes_supported": ["form_post", "fragment", "query"],
  "scopes_supported": [
    "openid", "offline_access", "profile", "email", "phone", "roles",
    "admin_api", "admin_api_readonly", "admin_console_webhooks"
  ],
  "claims_supported": [
    "aud", "exp", "iat", "iss", "sub", "name", "given_name", "family_name",
    "preferred_username", "email", "email_verified", "phone_number",
    "phone_number_verified", "updated_at", "auth_time", "amr", "acr", "role", "idp"
  ],
  "id_token_signing_alg_values_supported": ["RS256"],
  "code_challenge_methods_supported": ["plain", "S256"],
  "subject_types_supported": ["public"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "private_key_jwt", "client_secret_basic"],
  "introspection_endpoint_auth_methods_supported": ["client_secret_post", "private_key_jwt", "client_secret_basic"],
  "revocation_endpoint_auth_methods_supported": ["client_secret_post", "private_key_jwt", "client_secret_basic"],
  "claims_parameter_supported": true,
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "authorization_response_iss_parameter_supported": true,
  "acr_values_supported": ["urn:oltin:ac:pwd", "urn:oltin:ac:mfa", "urn:oltin:ac:external"]
}
```

## Fields

### Issuer and endpoints

| Field | Value on OneiD | Meaning |
|---|---|---|
| `issuer` | `https://YOUR_ONEID/` | The issuer identifier. It ends with a slash. The `iss` claim in every token and the `iss` parameter in authorisation responses carry the same value. |
| `authorization_endpoint` | `https://YOUR_ONEID/connect/authorize` | Where the browser starts a sign-in. |
| `token_endpoint` | `https://YOUR_ONEID/connect/token` | Where clients exchange codes, refresh tokens and client credentials for tokens. |
| `userinfo_endpoint` | `https://YOUR_ONEID/connect/userinfo` | Returns claims about the user for a user access token. |
| `introspection_endpoint` | `https://YOUR_ONEID/connect/introspect` | Token introspection for confidential clients. |
| `revocation_endpoint` | `https://YOUR_ONEID/connect/revoke` | Revokes refresh tokens and access tokens. |
| `end_session_endpoint` | `https://YOUR_ONEID/connect/logout` | RP-initiated sign-out. |
| `jwks_uri` | `https://YOUR_ONEID/.well-known/jwks` | The public signing keys. |

Details of each endpoint are in [Endpoints](https://oltinid.com/docs/reference/endpoints/).

> **Warning:** If your library compares the issuer exactly, use the `issuer` value from discovery, including the trailing slash. `https://YOUR_ONEID` without the slash does not match.

### Flows

| Field | Value on OneiD | Meaning |
|---|---|---|
| `grant_types_supported` | `authorization_code`, `client_credentials`, `refresh_token` | The grants OneiD issues tokens for. Each client is allowed only the grants an administrator set for it. |
| `response_types_supported` | `code` | Only the authorization code flow. No implicit or hybrid flow. |
| `response_modes_supported` | `form_post`, `fragment`, `query` | How the authorisation response is returned. Use `query` (the default) or `form_post`. |
| `code_challenge_methods_supported` | `plain`, `S256` | PKCE methods. Always use `S256`. |
| `authorization_response_iss_parameter_supported` | `true` | Authorisation responses include an `iss` parameter (RFC 9207). Check that it equals the issuer. |

> **Note:** `fragment` is listed but is not recommended or tested with OneiD. Use `query` or `form_post`.

> **Warning:** `plain` is listed in `code_challenge_methods_supported`. Do not use it. Send `code_challenge_method=S256`.

### Scopes and claims

| Field | Value on OneiD | Meaning |
|---|---|---|
| `scopes_supported` | `openid`, `offline_access`, `profile`, `email`, `phone`, `roles`, `admin_api`, `admin_api_readonly`, `admin_console_webhooks` | The identity scopes and OneiD's own administration scopes. Do not use the administration scopes in your applications. API scopes that your administrator creates, such as `orders.read`, may not appear here; ask your OneiD administrator which API scopes exist. |
| `claims_supported` | `aud`, `exp`, `iat`, `iss`, `sub`, `name`, `given_name`, `family_name`, `preferred_username`, `email`, `email_verified`, `phone_number`, `phone_number_verified`, `updated_at`, `auth_time`, `amr`, `acr`, `role`, `idp` | Claims OneiD can issue. Which ones you receive depends on the scopes granted. See [Claims](https://oltinid.com/docs/reference/claims/). |
| `claims_parameter_supported` | `true` | The `claims` request parameter is read for the `id_token` and `userinfo` members. |
| `subject_types_supported` | `public` | Each user has the same `sub` for every client. |
| `acr_values_supported` | `urn:oltin:ac:pwd`, `urn:oltin:ac:mfa`, `urn:oltin:ac:external` | The values the `acr` claim in the ID token can take. Sending `acr_values` in a request has no effect. |

### Signing and client authentication

| Field | Value on OneiD | Meaning |
|---|---|---|
| `id_token_signing_alg_values_supported` | `RS256` | ID tokens are signed with RS256. Access tokens use the same algorithm. |
| `token_endpoint_auth_methods_supported` | `client_secret_post`, `private_key_jwt`, `client_secret_basic` | How confidential clients authenticate at the token endpoint. Use `client_secret_basic`; `client_secret_post` is also accepted. |
| `introspection_endpoint_auth_methods_supported` | Same as above | Client authentication at the introspection endpoint. |
| `revocation_endpoint_auth_methods_supported` | Same as above | Client authentication at the revocation endpoint. |

> **Not supported:** `private_key_jwt` is listed, but there is no way to register a client's public key, so it cannot be used. Clients authenticate with a client secret. Mutual TLS client authentication is not supported.

### Request objects

| Field | Value on OneiD | Meaning |
|---|---|---|
| `request_parameter_supported` | `false` | Signed request objects in a `request` parameter are not accepted. OneiD answers with `request_not_supported`. |
| `request_uri_parameter_supported` | `false` | `request_uri` is not accepted. OneiD answers with `request_uri_not_supported`. |

### Fields that are absent

The document has no `registration_endpoint`, `device_authorization_endpoint`, `pushed_authorization_request_endpoint`, `check_session_iframe`, `frontchannel_logout_supported` or `backchannel_logout_supported`. OneiD does not offer these features. See [Standards support](https://oltinid.com/docs/reference/standards-support/).

## Caching

- Fetch the document once when your application starts, and keep it in memory. Do not fetch it on every request.
- Refresh it from time to time, for example once a day, and when calls start failing in a way that suggests a changed configuration.
- Fetch the [JWKS](https://oltinid.com/docs/reference/endpoints/#jwks) separately and refresh it when a token carries a `kid` you do not know. Mainstream OpenID Connect libraries do both for you.
- Discovery and JWKS answer requests from any origin, so a browser application can fetch them directly.

## Learn more

- [Endpoints](https://oltinid.com/docs/reference/endpoints/)
- [Tokens](https://oltinid.com/docs/reference/tokens/)
- [Standards support](https://oltinid.com/docs/reference/standards-support/)