Register Applications with CIMD

Register an application in Auth0 by importing an externally hosted Client ID Metadata Document (CIMD) from a URL. A CIMD is a JSON file containing client metadata hosted on your domain (e.g., https://example-client.com/mcp-metadata.json). The CIMD URL is the application’s client ID and proves domain ownership, ensuring only trusted tenant administrators can register applications. When you import an application from its CIMD URL, Auth0 fetches, validates, and persists the metadata to register the application as a CIMD client. While Auth0 maintains a record of these settings, the hosted CIMD remains the source of truth; metadata updates are synchronized through manual refreshes. This application registration process is called manual CIMD registration. You can only register third-party applications using manual CIMD, which are subject to enhanced security controls. Once registered, set up your CIMD client as a third-party application in Auth0.

Key benefits

Manual CIMD registration has the following benefits:

Uses asymmetric cryptography (public/private keys) instead of shared symmetric secrets that can be leaked.
Application owners manage client metadata directly in the CIMD; Auth0 simply pulls and persists these updates.
The client ID is the CIMD URL hosted on a secure HTTPS domain, which serves as a human-readable proof of ownership in audit logs.

Third-party applications, including CIMD clients, do not support Organizations. Organizations support for third-party applications will be introduced in a future release.

Rate limits for CIMD clients will be introduced in a future release. You will be able to set a specific rate limit for a CIMD client, as well as a shared rate limit on the aggregated traffic from all CIMD clients in a tenant.

Use cases

Common use cases for manual CIMD registration include:

MCP clients: Only need to be registered with CIMD once per deployment. All instances of that deployment use the same registration credentials. To learn how Auth0 secures MCP clients and servers, read Auth for MCP.
Third-party integrations: Partner applications, SaaS platforms, and external services that authenticate users on behalf of organizations. These applications manage their own client metadata and cryptographic keys, enabling independent updates and key rotation without sharing secrets.

Example CIMD

The following is an example CIMD for a public MCP client, where "token_endpoint_auth_method": "none":

https://example-client.com/mcp-metadata.json

{
  "client_id": "https://example-client.com/mcp-metadata.json",
  "client_name": "Example MCP Tool Server",
  "description": "MCP server providing tools for data analysis",
  "logo_uri": "https://example-client.com/logo.png",
  "application_type": "web",
  "grant_types": ["authorization_code", "refresh_token"],
  "redirect_uris": [
    "https://example-client.com/callback"
  ],
  "token_endpoint_auth_method": "none",
  "response_types": ["code"]
}

Auth0 automatically maps and validates CIMD fields. To learn more about supported client types, read Prerequisites.

How it works

The following diagram shows the end-to-end manual CIMD registration flow:

Phase 1: Registration
Phase 2: Authorization

Phase 1: Registration

During manual CIMD registration, a tenant admin registers the application by importing its externally hosted CIMD to Auth0:

Application creation: The tenant admin creates a CIMD app in Auth0 by:
- Selecting Import from URL in the Auth0 Dashboard
- Making a POST request to the /register endpoint, providing the external_client_id
Metadata fetch: Auth0 makes a GET request to the client’s domain to retrieve the CIMD (client.json).
Security validation: Auth0 maps and validates the CIMD URL against the CIMD URL validation rules and the CIMD against the CIMD validation rules, verifying that the external_client_id matches the CIMD URL, among other checks.
Persistence: Once validated, Auth0 stores the client metadata in the database.
Confirmation: Auth0 returns a success response; the application has been successfully registered as a CIMD client in Auth0.

Phase 2: Authorization

Once registered, the application uses its CIMD URL as its identity during the OAuth flow.

User-initiated task: The user initiates a task that requires the application to access an API.
Authorization request: The application makes a request to the Auth0 Authorization Server, passing its CIMD URL as the client_id.
Client resolution: The Auth0 Authorization Server queries the database to resolve the provided URL (client_id) to the stored client configuration (external_client_id).
User consent: Auth0 displays a consent screen to the user, identifying the application by the client_name retrieved from the CIMD metadata.
Redirection: After the user approves consent, Auth0 redirects the user back to the application with an authorization code.
Code exchange: The application exchanges the authorization code for an access token at the token endpoint.
Authorization complete: The Auth0 Authorization Server returns an access token where the client_id is set to the CIMD URL. The application can now access the API on the user’s behalf.

Prerequisites

Before registering an application with manual CIMD, make sure your tenant and application meet the following requirements:

Tenant configuration

Enable CIMD support: Enable the Client ID Metadata Document Registration toggle in your tenant settings to import CIMD via URL.
- Navigate to Settings > Advanced and scroll down to the Settings section.
- Toggle on Client ID Metadata Document Registration.
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 manual 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. Once registered, set up your CIMD client as a third-party application in Auth0.

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.

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

Register applications with manual CIMD

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

Auth0 Dashboard
Management API

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

Navigate to Applications > Applications.
Select Create Application > Import from URL.
Enter the CIMD URL. Then, select Preview. Auth0 validates the CIMD URL against the CIMD URL validation rules.
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.
Select Create.

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

Preview CIMD: Validate the CIMD URL and CIMD with Auth0
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:

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'"
    ]
  }
}

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.The following request passes https://mcpserver.example.com/client.json as the external_client_id to the /api/v2/clients/cimd/register endpoint:

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'"
    ]
  }
}

Set up CIMD client

Manual CIMD registration is limited to third-party applications (is_first_party: false), which are subject to enhanced security controls. Once you’ve registered your CIMD client, set it up as a third-party application in Auth0:

Configure API access policy: Create client grants to authorize its access to APIs
Promote connections to the domain level: Make connections available on the domain or tenant level to authenticate your users

To learn more, read Configure Third-Party Applications.

Refresh client metadata

Once you’ve registered the CIMD client, 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:

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

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:

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:

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, and more.

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:

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:

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"
  }'

CIMD URL validation rules

To pass validation in Auth0, CIMD URLs must meet the following requirements:

Category	Rule	Requirement
Protocol	HTTPS Required	Must use the `https://` scheme.
Host	No Localhost	`localhost`, `127.0.0.1`, and `::1` are rejected.
	Valid Hostname	Must contain a non-empty hostname; triple-slashes (e.g., `https:///`) are forbidden.
Path	Path Component	Must contain a path beyond the root `/`.
	No Dot Segments	Must not contain `.` or `..` (including encoded `%2e`) in the path.
Constraints	Length Limit	Maximum of 120 bytes.
	No Whitespace	No leading or trailing whitespace allowed.
	Format	Must be a non-empty string parseable as a URL.
Forbidden	No Credentials	No username or password allowed in the URL.
	No Fragments	Fragment identifiers (`#`) are not permitted.
	No Query	Query strings (`?`) are not permitted.
	No Port 0	Port 0 is reserved and forbidden.
Encoding	Percent-Encoding	`%` must be followed by exactly two hex digits.

CIMD JSON validation rules

Auth0 applies the following CIMD JSON validation rules:

Unsupported properties: Auth0 ignores unsupported properties during mapping and reports them as warnings in the validation response.
Inline JWKS: Providing an inline jwks object instead of a jwks_uri is not supported and will trigger an invalid_client_metadata error.
Private keys: Any JWKS retrieved via jwks_uri that contains private key material (the d parameter) will be rejected.
Fetch security: Both the CIMD document and the jwks_uri are subject to 5KB and 12KB size limits, respectively, and neither supports HTTP redirects.

Auth0 supports the following CIMD properties:

Property	Required	Type	Validation Rules	Auth0 Mapping
`client_id`	Yes	String	Must be a valid HTTPS URL that exactly matches the document’s hosted location.	`external_client_id`
`client_name`	Yes	String	Must be a non-empty string.	`name`
`redirect_uris`	Conditional	String Array	Required if `grant_types` includes `authorization_code` or `implicit`. Must be unique HTTPS URIs (loopback allowed for native apps).	`callbacks`
`grant_types`	Yes	String Array	Must include at least one supported type (`authorization_code` or `refresh_token`). Unsupported types trigger warnings and are filtered out.	`grant_types`
`application_type`	No	String	Only `native` or `web` are allowed. Unknown values are rejected. Defaults to `web`.	`app_type`
`token_endpoint_auth_method`	No	String	Supports `none` or `private_key_jwt`. Symmetric secret methods (e.g., `client_secret_post`) are forbidden.	`token_endpoint_auth_method`
`jwks_uri`	Conditional	String	Required if `token_endpoint_auth_method` is `private_key_jwt`. Must be an HTTPS URL sharing the same origin as the `client_id`.	`jwks_uri`
`logo_uri`	No	String	Must be a valid HTTP or HTTPS URL.	`logo_uri`
`description`	No	String	Free text with a maximum limit of 140 characters.	`description`
`response_types`	No	String Array	Validated for OIDC consistency but not persisted. Generates a warning if it contains `code` while `authorization_code` is missing from `grant_types`.	(None)

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. Make sure you refresh your key registration in Auth0 after rotating your keys. To learn more, read Rotate signing keys.

Auth0 Onboarding

Learn the Basics

Configure Auth0

Plan and Design

Auth0 AI

Universal Components

Register Applications with CIMD

Key benefits

Use cases

Example CIMD

How it works

Phase 1: Registration

Phase 2: Authorization

Prerequisites

Tenant configuration

Supported client types

Supported authentication methods

Register applications with manual CIMD

Preview CIMD

Register CIMD client

Set up CIMD client

Refresh client metadata

Get CIMD client

Update CIMD client

CIMD URL validation rules

CIMD JSON validation rules

Security considerations

CIMD client key rotation for private_key_jwt authentication

Auth0 Onboarding

Learn the Basics

Configure Auth0

Plan and Design

Auth0 AI

Universal Components

Documentation Index

​Key benefits

​Use cases

​Example CIMD

​How it works

​Phase 1: Registration

​Phase 2: Authorization

​Prerequisites

​Tenant configuration

​Supported client types

​Supported authentication methods

​Register applications with manual CIMD

​Preview CIMD

​Register CIMD client

​Set up CIMD client

​Refresh client metadata

​Get CIMD client

​Update CIMD client

​CIMD URL validation rules

​CIMD JSON validation rules

​Security considerations

​CIMD client key rotation for private_key_jwt authentication

Key benefits

Use cases

Example CIMD

How it works

Phase 1: Registration

Phase 2: Authorization

Prerequisites

Tenant configuration

Supported client types

Supported authentication methods

Register applications with manual CIMD

Preview CIMD

Register CIMD client

Set up CIMD client

Refresh client metadata

Get CIMD client

Update CIMD client

CIMD URL validation rules

CIMD JSON validation rules

Security considerations

CIMD client key rotation for private_key_jwt authentication