# Manage OAuth clients with Client ID Metadata Documents (Beta)

> **Beta:** Client ID Metadata Documents are currently in beta. To have them enabled for your account, [contact support](https://clerk.com/contact/support).

A Client ID Metadata Document (CIMD) lets an OAuth client use an HTTPS URL as its `client_id`. The URL serves a JSON document that describes the client, including its name and allowed redirect URIs. This lets Clerk identify a client without requiring it to create a registration through [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591).

Clerk's current OAuth implementation supports [Client ID Metadata Documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). You control client admission from the Clerk Dashboard: you can explicitly allow individual clients or allow previously unknown clients to connect.

While CIMD is in beta, the **CIMD Clients** tab appears on the [**OAuth applications**](https://dashboard.clerk.com/~/oauth-applications) page only after CIMD is enabled for your account. Applications that still use Clerk's legacy OAuth implementation don't support CIMD clients.

## Client metadata requirements

The following example demonstrates the minimum metadata that a client can publish:

filename: client-metadata.json
```json
{
  "client_id": "https://client.example.com/oauth/client-metadata.json",
  "client_name": "Example client",
  "redirect_uris": ["https://client.example.com/oauth/callback"],
  "token_endpoint_auth_method": "none"
}
```

For Clerk to accept the document:

- The `client_id` must be an HTTPS URL with a path.
- The document's `client_id` must exactly match the URL Clerk fetched.
- `client_name` and at least one `redirect_uris` entry must be present.
- The requested `redirect_uri` must exactly match an entry in `redirect_uris`.
- The client must be public. Clerk rejects metadata that contains a client secret or selects a secret-based token endpoint authentication method.

Clerk treats all CIMD clients as public OAuth clients, requires Proof Key for Code Exchange (PKCE) with the `S256` method, and always shows the OAuth consent screen.

> CIMD clients require a reachable OAuth consent flow. Keep the Account Portal enabled or configure an OAuth consent page for your application before you allow a CIMD client or let unknown clients connect.

## Explicitly allow a client

Explicitly allowed clients can start OAuth flows regardless of the unknown-client policy.

1. ## Open the CIMD Clients tab

   In the Clerk Dashboard, navigate to the [**OAuth applications**](https://dashboard.clerk.com/~/oauth-applications) page and open the **CIMD Clients** tab.
2. ## Add the client

   Select **Pre-register**, or **Allow client** if no clients are listed yet. Then configure:

   - **Client ID URL**: The HTTPS URL that serves the client's metadata document.
   - **Scopes**: The scopes that the client may request from this Clerk instance.

   Clerk reads the client's name and logo from its metadata document. The document can't grant itself additional scopes, so the scopes selected in the Clerk Dashboard remain authoritative. Clerk always includes `offline_access` for CIMD clients.
3. ## Allow the client

   Select **Allow client**. Clerk fetches the metadata document and records the client as **Explicitly allowed**.

   If Clerk can't fetch the document, the client remains explicitly allowed and its metadata status displays **Error**. The OAuth flow can't complete until Clerk can resolve a valid metadata document. From the client's actions menu, select **Refresh metadata** after the document becomes available.

## Configure CIMD settings

The **Settings** section on the **CIMD Clients** tab controls how Clerk advertises CIMD and which clients may connect:

| Setting                                          | Behavior                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Advertise CIMD support**                       | Publishes `client_id_metadata_document_supported` in your instance's OAuth authorization server metadata so compatible clients can select CIMD instead of Dynamic Client Registration. This setting also gates whether unknown clients may connect. Explicitly allowed clients can connect either way. |
| **Default scopes**                               | The scopes Clerk applies when a CIMD client omits the `scope` parameter. At least one scope is required, and Clerk includes `offline_access` automatically. Select **Restore Clerk defaults** to return to Clerk's own defaults. Available when **Advertise CIMD support** is enabled.                 |
| **Only allow pre-registered clients to connect** | Restricts new OAuth flows to clients on the **CIMD clients** list. Clients that already connected keep their access.                                                                                                                                                                                   |
| **Block implicitly allowed clients**             | Blocks future OAuth flows for clients that Clerk recorded when they first connected. Available after you enable **Only allow pre-registered clients to connect**.                                                                                                                                      |

**Advertise CIMD support**, **Only allow pre-registered clients to connect**, and **Block implicitly allowed clients** are all disabled by default.

> Enabling **Advertise CIMD support** also lets any CIMD client connect, and Clerk records each one as **Implicitly allowed**. Enable **Only allow pre-registered clients to connect** if you want to review clients before they can start an OAuth flow.

Enabling **Only allow pre-registered clients to connect** prevents new unknown clients from connecting, but doesn't change clients that Clerk already recorded as implicitly allowed. Enable **Block implicitly allowed clients** if you also want to block those previously connected clients. Blocking an implicitly allowed client doesn't delete its record or revoke tokens that Clerk already issued.

You can explicitly allow an implicit or blocked client from its actions menu. Explicitly allowed clients aren't affected by the **Block implicitly allowed clients** setting.

## Review and manage clients

The **CIMD clients** table displays each client's:

- Client ID URL and display name
- Allowed scopes
- Admission status
- Metadata fetch status
- Creation date

The admission statuses are:

| Status                 | Meaning                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| **Explicitly allowed** | An administrator allowed the client from the Clerk Dashboard.                               |
| **Implicitly allowed** | Clerk recorded the client the first time it connected, while unknown clients were allowed.  |
| **Blocked**            | The client was implicitly allowed, but **Block implicitly allowed clients** is now enabled. |

From a client's actions menu, you can:

- Explicitly allow an implicit or blocked client.
- Edit the scopes it may request.
- Refresh its metadata.
- Delete the saved client.

> If you delete a client while unknown clients are allowed, the client can connect again and Clerk records it as implicitly allowed.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)