> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Client ID Metadata Document (CIMD) Registration

> Learn about Client ID Metadata Document (CIMD) registration in Auth0, including its benefits, use cases, and how manual and dynamic CIMD work.

> [!WARNING]
>
> **The Dynamic CIMD Registration feature is in .**

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 applications can be registered in Auth0. While Auth0 maintains a record of these settings, the hosted CIMD remains the source of truth.

Auth0 supports manual CIMD and dynamic CIMD registration:

* Manual CIMD registration: Manually import an application from its CIMD URL. Auth0 fetches and validates the CIMD to register the application as a CIMD client; metadata updates are synchronized through manual refreshes.
* Dynamic CIMD registration: The application registers itself via its CIMD URL at runtime when it sends an OAuth request to Auth0; metadata updates are synchronized reactively on-demand for authorization requests.

Only [third-party applications](/docs/get-started/applications/third-party-applications) can be registered with CIMD, which are subject to [enhanced security controls](/docs/get-started/applications/third-party-applications/security-controls.md). To learn more, read [Register Applications with CIMD](/docs/get-started/auth0-overview/create-applications/register-applications-with-cimd.md).

For dynamically registered CIMD clients, tenant administrators can use [Application Profiles](/docs/get-started/applications/application-profiles.md) to apply consistent application settings around refresh token lifetimes, Organizations behavior, and more.

CIMD clients always register with `third_party_security_mode: "strict"`, regardless of your tenant's **Create Permissive Third-Party Clients by Default** setting. Permissive mode is not available for CIMD clients. Strict third-party applications [do not support Rules](/docs/get-started/applications/third-party-applications/security-controls.md#features-not-supported), and login flows for CIMD clients fail if your tenant has active Rules. If you use Rules, [migrate to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions.md) before registering CIMD clients.

You cannot switch a CIMD client from manual or dynamic once registered. To do so, delete and re-register the client.

## Key benefits

CIMD registration have the following benefits:

1. MCP clients only need to be registered with CIMD once per deployment. All instances of that deployment use the same registration credentials.
2. Registration uses asymmetric cryptography (public/private keys) instead of shared symmetric secrets that can be leaked.
3. Application owners manage client metadata directly in the CIMD; Auth0 automatically maps these properties to its internal configuration during registration.
4. The CIMD URL acts as a human-readable identifier in audit logs, making it easy to verify the origin of requests from specific MCP tool servers or hosts.

## Use cases

Common use cases for 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](/ai/docs/mcp/overview.md).
* 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, in which `"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](/docs/get-started/auth0-overview/create-applications/cimd-validation-rules.md#cimd-json-validation-rules). To learn more about supported client types, read [Prerequisites](/docs/get-started/auth0-overview/create-applications/register-applications-with-cimd.md#prerequisites).

## Manual vs. dynamic CIMD registration

The following table compares manual CIMD registration and dynamic CIMD registration:

| Feature | Manual CIMD Registration | Dynamic CIMD Registration |
| - | - | - |
| **Client ID** | HTTPS URL (e.g., `https://yourdomain.com/client.json`) | HTTPS URL (e.g., `https://yourdomain.com/client.json`) |
| **Authentication** | Asymmetric keys only (no secrets) | Asymmetric keys only (no secrets) |
| **Identity verification** | Domain ownership via HTTPS hosting | Domain ownership via HTTPS hosting |
| **Registration trigger** | Tenant admin imports the application from its CIMD URL | Application registers itself at runtime on its first OAuth request |
| **Metadata management** | Source of truth is CIMD; refreshed manually | Source of truth is CIMD; refreshed automatically (reactively and in the background) |
| **Admin review of metadata changes** | Admin reviews and approves changes before they apply | No admin review; validated changes apply automatically |
| **Key rotation** | Multiple keys supported in `jwks_uri`; refreshed manually | Multiple keys supported in `jwks_uri`; resolved automatically on demand |
| **Application type** | Third-party applications only | Third-party applications only |
| **Typical use cases** | MCP clients, third-party integrations | High-volume or ephemeral clients, such as AI agents, that register without manual provisioning |

## Dynamic CIMD client limit

Each tenant can have a maximum of 500 dynamically registered CIMD clients. Only clients that applications registered themselves at runtime count toward this limit. CIMD clients that a tenant admin imported manually do not.

Dynamically registered CIMD clients also count toward your tenant's total [Applications entity limit](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy.md#enterprise), so each one uses a slot in both counts.

The Dynamic CIMD client limit can be adjusted for individual tenants. To request a different limit, contact [Auth0 Support](https://support.auth0.com/).

## How it works

Learn about how CIMD registration works in Auth0:

**Manual CIMD registration**

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

* [Phase 1: Registration](#phase-1-registration)
* [Phase 2: Authorization](#phase-2-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<br/>(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<br/>(Auth0 resolves client by external_client_id == client_id)
    Auth0->>User: Consent screen<br/>(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<br/>(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](/docs/get-started/auth0-overview/create-applications/cimd-validation-rules.md#cimd-url-validation-rules) and the CIMD against the [CIMD validation rules](/docs/get-started/auth0-overview/create-applications/cimd-validation-rules.md#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.

**Dynamic CIMD registration**

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

```mermaid theme={null}
sequenceDiagram
      actor User
      participant CA as Client App
      participant AS as Authorization Server
      participant CD as Client's Domain (Hosts JSON)

      User->>CA: 1. Start Login
      CA->>AS: 2. Auth Request (client_id=https://...)

      alt Metadata Cached and Fresh
          AS->>AS: 3. Retrieve Cached Metadata
      else Metadata Missing or Stale
          AS->>CD: 3. GET /.../client-metadata.json
          CD-->>AS: 4. Returns client-metadata.json
          AS->>AS: 5. Validate Metadata (SSRF checks, etc.)
          AS->>AS: Create Non-Validated Client Record
      end

      AS->>User: 6. Show Consent Screen (using client_name)
      User->>AS: 7. Approve Consent
      AS-->>CA: 8. Redirect with Authorization Code

      CA->>AS: 9. Request Token (with Code)
      AS-->>CA: 10. Return Access Token
```

During dynamic CIMD registration, the application registers itself with Auth0 at runtime, without a prior manual registration step:

1. **Start login**: The user initiates a login from the client application.
2. **Authorization request**: The application sends an authorization request to the Auth0 Authorization Server, passing its CIMD URL as the `client_id`.
3. **Metadata resolution**: If Auth0 already has fresh, cached metadata for the client, it uses the cached copy and skips the next steps. Otherwise, Auth0 sends a `GET` request to the client's domain to retrieve the CIMD (`client-metadata.json`).
4. **Metadata returned**: The client's domain returns the CIMD.
5. **Security validation**: Auth0 validates the CIMD against the [CIMD URL validation rules](/docs/get-started/auth0-overview/create-applications/cimd-validation-rules.md#cimd-url-validation-rules) and [CIMD JSON validation rules](/docs/get-started/auth0-overview/create-applications/cimd-validation-rules.md#cimd-json-validation-rules), including SSRF checks, and registers the application as a non-validated CIMD client.
6. **User consent**: Auth0 displays a consent screen to the user, identifying the application by the `client_name` retrieved from the CIMD metadata.
7. **Approve consent**: The user approves the consent request.
8. **Redirection**: Auth0 redirects the user back to the application with an authorization code.
9. **Token request**: The application exchanges the authorization code for an [access token](/docs/secure/tokens/access-tokens.md) at the token endpoint.
10. **Access token returned**: The Auth0 Authorization Server returns an access token to the application. The application can now access the API on the user's behalf.

## Get started