Register Applications with CIMD

Learn how to register applications with the Client ID Metadata Document (CIMD).

To learn about Client ID Metadata Document (CIMD) registration, including its benefits, use cases, and how manual and dynamic CIMD work, read CIMD Overview.

Prerequisites

Before registering an application with CIMD, make sure you meet the following requirements:

Tenant and application configuration

Only third-party applications can be registered as CIMD clients:

• Configure the API access policy: Third-party applications require explicit client grants to access APIs.
• Promote connections to the domain level: Make connections available on the domain or tenant level to authenticate your users, which is required for third-party applications.
• Resource Parameter Compatibility Profile (Optional): For MCP clients, we recommend enabling this profile in your tenant settings. This allows the authorization server to handle resource-specific requests (RFC 8707) by checking the resource parameter if the audience is not provided.

Supported client types

You can register the following client types with CIMD in Auth0:

• Application type: Must be a native or regular web application.
• Third-party application: Must be a third-party application (is_first_party: false), which is subject to enhanced security controls.

Supported authentication methods

CIMD clients cannot use authentication methods based on shared symmetric secrets, such as client_secret_post, client_secret_basic, or client_secret_jwt.

Depending on whether the client is public or confidential, Auth0 supports the following authentication methods for CIMD clients:

• Public clients:
  • No client authentication required at the token endpoint; set token_endpoint_auth_method to none in client metadata
  • Must use Proof Key for Code Exchange (PKCE) for authorization flows
• Confidential clients:
  • Only Private Key JWT authentication is supported; set token_endpoint_auth_method to private_key_jwt in client metadata
  • Provide a jwks_uri to host public keys. The jwks_uri must share the exact same origin (scheme, host, and port) as the CIMD URL. To learn more, read CIMD JSON validation rules.

Private Key JWT authentication is available only for Enterprise customers. To learn more about Enterprise plans, review Pricing or contact Auth0 Sales.

Manual CIMD clients that use Private Key JWT authentication must implement key rotation by generating a new key pair with a new, unique kid.

Enable CIMD registration

Enable CIMD registration with the Auth0 Dashboard or Management API.

Auth0 Dashboard

• Enable CIMD support: Enable the Client ID Metadata Document Registration toggle in your tenant settings to indicate CIMD support in the Auth0 Authorization Server metadata, allowing clients to automatically discover this capability when connecting.
  • Navigate to Settings > Advanced and scroll down to the Settings section.
  • Toggle on Client ID Metadata Document Registration.
• Dynamic CIMD Registration support: Enable the Dynamic CIMD Registration toggle underneath Client ID Metadata Document Registration in your tenant settings. When enabled, new clients can register themselves via Dynamic CIMD. When disabled, new clients cannot register themselves via dynamic CIMD, but existing dynamic CIMD clients still work as expected.

Management API

The Client ID Metadata Document Registration toggle corresponds to the client_id_metadata_document_supported property, and Dynamic CIMD Registration corresponds to client_id_metadata_document_dynamic_registration_supported, both on the PATCH /api/v2/tenants/settings endpoint.

client_id_metadata_document_dynamic_registration_supported requires client_id_metadata_document_supported to be true, and client_id_metadata_document_supported cannot be disabled while client_id_metadata_document_dynamic_registration_supported is true. Attempting either returns a 400 Bad Request error, for example:

{
  "statusCode": 400,
  "error": "Bad Request",
  "errorCode": "validation_error",
  "message": "client_id_metadata_document_dynamic_registration_supported cannot be enabled when client_id_metadata_document_supported is false. Enable client_id_metadata_document_supported in the same request or beforehand."
}

If your tenant doesn’t have access to Dynamic CIMD Registration, setting client_id_metadata_document_dynamic_registration_supported returns a 403 Forbidden error:

{
  "statusCode": 403,
  "error": "Forbidden",
  "errorCode": "not_entitled",
  "message": "Updating the client_id_metadata_document_dynamic_registration_supported setting is not allowed for this tenant."
}

Register applications with CIMD

When creating an application in Auth0, register it manually with CIMD using the Auth0 Dashboard or Management API.

When dynamic CIMD registration is enabled, applications register themselves at runtime via their CIMD URL with Auth0. To enable Dynamic CIMD registration, read Enable CIMD registration.

Auth0 Dashboard

To register an application with manual CIMD using the Auth0 Dashboard:

1. Navigate to Applications > Applications.
2. Select Create Application > Import from URL.
3. Enter the CIMD URL. Then, select Preview. Auth0 validates the CIMD URL against the CIMD URL validation rules.
4. If your CIMD URL is valid, Auth0 loads the CIMD and validates it against the CIMD JSON validation rules. Preview your client metadata and troubleshoot it for any validation errors.
5. Select Create.

Management API

To register an application with manual CIMD using the Management API:

1. Preview CIMD: Validate the CIMD URL and CIMD with Auth0
2. Register CIMD client: Register the application as a CIMD client in Auth0

Preview CIMD

To preview the CIMD, make a POST request to the /api/v2/clients/cimd/preview endpoint and pass the following:

• external_client_id: The CIMD URL for the application

The /api/v2/clients/cimd/preview endpoint loads and validates the external_client_id and the CIMD at that URL, allowing you to preview the client metadata and any validation errors.

The following request passes https://mcpserver.example.com/client.json as the external_client_id to the /api/v2/clients/cimd/preview endpoint:

Auth0 CLI

Using the Auth0 CLI? If you haven’t already, set up and authenticate your CLI session before running this command.

auth0 api post "clients/cimd/preview" \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

cURL

curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/cimd/preview' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

If successful, Auth0 returns a response like the following:

{
  "mapped_fields": {
    "external_client_id": "https://mcpserver.example.com/client.json",
    "redirect_uris": ["https://mcpserver.example.com/callback"],
    "client_name": "MCP Tool Server",
    "logo_uri": "https://mcpserver.example.com/logo.png",
    "grant_types": ["authorization_code"],
    "scope": "read write"
  },
  "validation": {
    "valid": true,
    "warnings": [
      "Grant type not supported: 'implicit'",
      "Property not supported: 'nfv_token_signed_response_alg'"
    ]
  }
}

If a client is already registered with the external_client_id you previewed, the response also includes client_id and external_metadata_created_by:

{
  "mapped_fields": { "..." },
  "validation": { "valid": true, "violations": [], "warnings": [] },
  "client_id": "YOUR_CLIENT_ID",
  "external_metadata_created_by": "client"
}

external_metadata_created_by indicates how the existing client was registered:

Value	Description
client	The application dynamically registered itself via its CIMD URL at runtime.
admin	A tenant admin manually registered the application from its CIMD URL.

Register CIMD client

Once you’ve verified the client metadata, make a POST request to the /api/v2/clients/cimd/register endpoint and pass the following:

• external_client_id: The CIMD URL for the application

The /api/v2/clients/cimd/register endpoint registers the CIMD application. If a manual CIMD client already exists with that external_client_id, Auth0 updates the existing client instead of creating a new one. If a dynamic CIMD client already exists with that external_client_id, the request fails with a 409 Conflict error.

The following request passes https://mcpserver.example.com/client.json as the external_client_id to the /api/v2/clients/cimd/register endpoint:

Auth0 CLI

auth0 api post "clients/cimd/register" \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

cURL

curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/cimd/register' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

If successful, Auth0 returns a response like the following:

Location: /api/v2/clients/YOUR_CLIENT_ID
{
  "client_id": "YOUR_CLIENT_ID",
  "mapped_fields": {
    "external_client_id": "https://mcpserver.example.com/client.json",
    "redirect_uris": ["https://mcpserver.example.com/callback"],
    "client_name": "MCP Tool Server",
    "logo_uri": "https://mcpserver.example.com/logo.png",
    "grant_types": ["authorization_code"],
    "scope": "read write"
  },
  "validation": {
    "valid": true,
    "warnings": [
      "Grant type not supported: 'implicit'",
      "Property not supported: 'nfv_token_signed_response_alg'"
    ]
  }
}

Refresh client metadata

Manual CIMD clients and dynamic CIMD clients refresh client metadata in different ways.

Manual CIMD clients

For manual CIMD clients, you can manually refresh client metadata. Auth0 fetches fresh client metadata from the CIMD, which you can preview and save.

When you refresh client metadata, Auth0 updates the app_type and grant_types to match the values in the hosted CIMD. To learn more about CIMD fields, read CIMD JSON validation rules.

In the Auth0 Dashboard:

1. Navigate to Applications > Applications and select your CIMD client.
2. At the top-right corner, select Refresh Client Metadata.
3. Select Refresh Preview to preview the latest client metadata in the CIMD. Review any validation warnings or errors.
4. Select Save.

Dynamic CIMD clients

For dynamic CIMD clients, Auth0 fetches the latest CIMD document automatically in the following cases:

• When the client makes an OAuth request to Auth0 on first discovery
• When a cached copy of the CIMD is missing
• When something in the OAuth request fails validation, such as a redirect_uri mismatch

Unlike manual CIMD, where a tenant admin reviews and approves metadata updates, dynamic CIMD re-fetches, validates, and applies refreshed metadata and key changes automatically to every tenant using that client; no per-tenant action is needed.

Frequently-used clients are refreshed periodically in the background before they go stale, so active users don’t experience added login latency waiting on a live metadata fetch. Less-used clients are only refreshed reactively, on demand.

Decoupled refresh cadence for metadata vs. keys

CIMD metadata (name, redirect URIs, etc.) and signing keys (JWKS) refresh on different schedules, since keys rotate far more often than metadata. This means a key rotation doesn’t force an unnecessary full metadata refetch, and vice versa.

Automatic key resolution

If Auth0 can’t find a signing key (kid) it needs during token validation, it automatically fetches the latest keys from the client’s jwks_uri on demand, rather than requiring a manual update.

Failure handling

If a client’s metadata URL or keys become temporarily unreachable or invalid, Auth0 backs off automatically rather than retrying immediately on every request. If validated metadata is fetched successfully but something in the request is still invalid, Auth0 fails that authorization request without re-fetching the document.

Get CIMD client

To get a CIMD client, make a GET request to the /v2/clients/{clientId} endpoint, where {clientID} is the Auth0-generated client ID assigned to the CIMD client:

Auth0 CLI

auth0 api get "clients/YOUR_CLIENT_ID"

cURL

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json'

Alternatively, pass the external_client_id, or the CIMD URL, as the query parameter to the /v2/clients endpoint:

Auth0 CLI

auth0 api get "clients" \
  -q "external_client_id=https://mcpserver.example.com/client.json"

cURL

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients?external_client_id=https://mcpserver.example.com/client.json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json'

If successful, Auth0 returns a response that includes the CIMD client configuration with fields like external_client_id, name, callbacks, token_endpoint_auth_method, external_metadata_created_by, external_metadata_status, and more.

CIMD metadata status

Every CIMD client includes an external_metadata_status field that indicates whether Auth0 could resolve the client’s hosted metadata document:

Value	Description
available	The metadata document was resolved. Manual CIMD clients always report available, since a tenant admin controls when metadata refreshes. For dynamic CIMD clients, available reflects resolution at a point in time and doesn’t guarantee the returned fields are the latest version. Auth0 may serve a recently cached copy of the metadata rather than re-fetching it on every request.
unavailable	Auth0 could not resolve the client’s metadata document, for example because the hosted CIMD URL is temporarily unreachable or returns invalid content. While unavailable, only name and app_type are returned, holding their last known (stale) values; the rest of the metadata-derived fields are omitted. Authentication requests for this client fail until the metadata becomes resolvable again.

A dynamic CIMD client with external_metadata_status: "unavailable" can recover on its own once its metadata URL becomes reachable again. Auth0 re-resolves the metadata automatically on a subsequent authentication request, with no manual action required. If the status remains unavailable for an extended period, consider deleting the client rather than waiting indefinitely.

To troubleshoot the CIMD metadata status, you can make a POST request to the /api/v2/clients/cimd/preview endpoint. If the URL is reachable but the CIMD metadata document is invalid, Auth0 will return validation errors.

Update CIMD client

You can update the fields in the Auth0 database for a registered CIMD client. Updating the CIMD client in Auth0 does not automatically update the CIMD hosted on the application’s domain.

You can only update the following fields for CIMD clients. Dynamic CIMD clients have further restrictions: you cannot update app_type, description, grant_types, and name.

Field	Description
app_type	The Auth0 application type. For CIMD, this maps from application_type and is restricted to native (for native apps) or regular_web (for web apps).
grant_types	The OAuth 2.0 grant types allowed. For CIMD, this is restricted to authorization_code and refresh_token. Other types are filtered out during mapping.
jwt_configuration.alg	The algorithm used to sign the ID Token. As strict third-party clients, CIMD applications are typically restricted to secure asymmetric algorithms such as RS256, RS512, or PS256.
description	A free-text description of the client. Mapped directly from CIMD metadata with a maximum limit of 140 characters.
oidc_conformant	Must be enabled for strict third-party clients. This ensures the client follows OIDC specifications and is generally not modifiable for CIMD clients.
allowed_origins	A list of URLs allowed for Cross-Origin Resource Sharing (CORS). Typically used by browser-based applications.
web_origins	A list of URLs allowed for web-based flows (e.g., Silent Authentication).
refresh_token.*	Configuration for refresh token behavior, including rotation_type, leeway, and various lifetime settings. These control how long a refresh token remains valid and if it rotates upon use.
organization_*	Settings for organization-specific flows, including usage, require_behaviour, discovery_methods, and default_organization. These determine how the client interacts with Auth0 Organizations.
client_metadata	Arbitrary key-value pairs used to store additional information about the client that does not map to standard Auth0 properties.
require_proof_of_possession	Indicates if the client must demonstrate proof of possession of a key, often used with DPoP or mTLS.

To update a CIMD client, make a PATCH request to the /v2/clients/{clientId} endpoint, where {clientID} is the Auth0-generated client ID assigned to the CIMD client:

Auth0 CLI

auth0 api patch "clients/YOUR_CLIENT_ID" \
  --data '{
    "description": "This is my test CIMD client"
  }'

cURL

curl --location --request PATCH \
  'https://YOUR_AUTH0_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --data '{
    "description": "This is my test CIMD client"
  }'

Security considerations

CIMD client key rotation for private_key_jwt authentication

To successfully rotate keys for CIMD clients using Private Key JWT authentication, generate a new key pair with a new, unique kid. If you rotate your private key and update your JWKS with new key material under the same kid, Auth0’s CIMD registration rejects the new key and preserves the old one. This ensures that key rotation requires explicit addition of new keys rather than silent replacement.

For manual CIMD clients, refresh your key registration in Auth0 after rotating your keys. To learn more, read Rotate signing keys.

For dynamic CIMD clients, no manual refresh is required: if Auth0 cannot find a signing key (kid) during token validation, it automatically fetches the latest keys from the client’s jwks_uri.

Credentials are not supported for dynamic CIMD clients

A dynamic CIMD client authenticates with keys resolved from its jwks_uri, so it has no stored credential records. Making a POST request to the /v2/clients/{id}/credentials endpoint for a dynamic CIMD client fails with the following error:

{
  "statusCode": 400,
  "error": "Bad Request",
  "errorCode": "client_credentials_not_supported",
  "message": "Credentials of dynamically registered CIMD clients are resolved from the jwks_uri of their client ID metadata document and cannot be managed through this endpoint."
}

To rotate the keys of a dynamic CIMD client, update the jwks_uri document hosted on its domain; Auth0 fetches the new keys automatically when needed. Reading, updating, or deleting credentials for a dynamic CIMD client is not blocked; since no credential record exists, these requests behave the same as they would for any client with no credentials (an empty list, a 404 Not Found for a specific credential ID, or an idempotent 204 No Content on delete). Manual CIMD clients and other application types are not affected by this restriction.