> ## Documentation Index > Fetch the complete documentation index at: https://docs-dev-actions-triggers-prototype.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Register Applications with CIMD > Learn how to register applications with the Client ID Metadata Document (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](#refresh-client-metadata). This application registration process is called manual CIMD registration. You can only register [third-party applications](/docs/get-started/applications/third-party-applications) using manual CIMD, which are subject to [enhanced security controls](/docs/get-started/applications/third-party-applications/security-controls). Once registered, [set up your CIMD client](#set-up-cimd-client) as a third-party application in Auth0. ## Key benefits Manual CIMD registration has the following benefits: 1. Uses asymmetric cryptography (public/private keys) instead of shared symmetric secrets that can be leaked. 2. Application owners manage client metadata directly in the CIMD; Auth0 simply pulls and persists these updates. 3. 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](https://auth0.com/ai/docs/mcp/intro/overview). * 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"`: ```json https://example-client.com/mcp-metadata.json wrap lines theme={null} { "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](#cimd-json-validation-rules). To learn more about supported client types, read [Prerequisites](#prerequisites). ## How it works The following diagram shows the end-to-end manual CIMD registration flow: * [Phase 1: Registration](#phase-1%3A-registration) * [Phase 2: Authorization](#phase-2%3A-authorization) ```mermaid theme={null} %%{init: { "sequence": { "mirrorActors": true }}}%% sequenceDiagram rect rgb(240, 248, 255) Note over Tenant Admin,Auth0: Registration Phase participant Tenant Admin participant Auth0 participant Domain Tenant Admin->>Auth0: Create CIMD app Auth0->>Tenant Admin: POST /register
(external_client_id = https://.../client.json) Auth0->>Domain: GET https://.../client.json Domain-->>Auth0: Client metadata (CIMD JSON) Auth0->>Auth0: Validate + store client end rect rgb(240, 255, 240) Note over Client,Auth0: Authorization Phase actor User participant Client participant Auth0 User->>Client: User-initiated task Client->>Auth0: /authorize?client_id = https://.../client.json
(Auth0 resolves client by external_client_id == client_id) Auth0->>User: Consent screen
(client metadata) User->>Auth0: Approve Auth0-->>Client: Authorization code Client->>Auth0: Exchange code Auth0->>Client: Complete authorization & redirect to client redirect_uri Client->>Auth0: Request resource access token with /oauth/token Auth0-->>Client: Return resource access token
(includes client_id=https://../client.json) end ``` ### Phase 1: Registration During manual CIMD registration, a tenant admin registers the application by importing its externally hosted CIMD to Auth0: 1. **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` 2. **Metadata fetch**: Auth0 makes a GET request to the client's domain to retrieve the CIMD (client.json). 3. **Security validation**: Auth0 maps and validates the CIMD URL against the [CIMD URL validation rules](#cimd-url-validation-rules) and the CIMD against the [CIMD validation rules](#cimd-json-validation-rules), verifying that the `external_client_id` matches the CIMD URL, among other checks. 4. **Persistence**: Once validated, Auth0 stores the client metadata in the database. 5. **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. 1. **User-initiated task**: The user initiates a task that requires the application to access an API. 2. **Authorization request**: The application makes a request to the Auth0 Authorization Server, passing its CIMD URL as the `client_id`. 3. **Client resolution**: The Auth0 Authorization Server queries the database to resolve the provided URL (`client_id`) to the stored client configuration (`external_client_id`). 4. **User consent**: Auth0 displays a consent screen to the user, identifying the application by the `client_name` retrieved from the CIMD metadata. 5. **Redirection**: After the user approves consent, Auth0 redirects the user back to the application with an authorization code. 6. **Code exchange**: The application exchanges the authorization code for an access token at the token endpoint. 7. **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](/docs/get-started/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**. * **Resource Parameter Compatibility Profile (Optional)**: For MCP clients, we recommend enabling this profile in your [tenant settings](/docs/get-started/tenant-settings). This allows the authorization server to handle resource-specific requests ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html#name-resource-parameter)) 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](/docs/get-started/applications/third-party-applications) (`is_first_party: false`), which is subject to [enhanced security controls](/docs/get-started/applications/third-party-applications/security-controls). Once registered, [set up your CIMD client](#set-up-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)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) for authorization flows * **Confidential clients**: * Only [Private Key JWT authentication](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt#authenticate-with-private-key-jwt) 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](#cimd-json-validation-rules). Private Key JWT authentication is available only for Enterprise customers. To learn more about Enterprise plans, review [Pricing](https://auth0.com/pricing) or contact [Auth0 Sales](https://auth0.com/contact-us). CIMD clients that use Private Key JWT authentication must [implement key rotation by generating a new key pair with a new, unique `kid`](#security-considerations). ## Register applications with manual CIMD When creating an application in Auth0, register it manually with CIMD using the Auth0 Dashboard or Management API. 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](#cimd-url-validation-rules). 4. If your CIMD URL is valid, Auth0 loads the CIMD and validates it against the [CIMD JSON validation rules](#cimd-json-validation-rules). Preview your client metadata and troubleshoot it for any validation errors. 5. Select **Create**. To register an application with manual CIMD using the Management API: 1. [Preview CIMD](#preview-cimd): Validate the CIMD URL and CIMD with Auth0 2. [Register CIMD client](#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: ```bash wrap lines theme={null} 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: ```json theme={null} { "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: ```bash wrap lines theme={null} 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: ```json theme={null} 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](/docs/get-started/applications/third-party-applications/security-controls). Once you've registered your CIMD client, set it up as a third-party application in Auth0: * [Configure API access policy](/docs/get-started/applications/third-party-applications/configure-third-party-applications#configure-api-access-policies): Create client grants to authorize its access to APIs * [Promote connections to the domain level](/docs/get-started/applications/third-party-applications/configure-third-party-applications#configure-connections): Make connections available on the domain or tenant level to authenticate your users To learn more, read [Configure Third-Party Applications](/docs/get-started/applications/third-party-applications/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](#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**. ## 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: ```bash wrap lines theme={null} 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: ```bash wrap lines theme={null} 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: ```bash wrap lines theme={null} 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](/docs/secure/tokens/json-web-tokens/json-web-key-sets#rotate-signing-keys).