Manage OAuth clients with Client ID Metadata Documents, Beta

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⁠.

Clerk's current OAuth implementation supports Client ID Metadata Documents⁠. 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⁠ 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:

{
  "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.

Explicitly allow a client

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

Configure CIMD settings

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

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

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:

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.