Configure a CIMD client

Register a Client ID Metadata Document (CIMD) client so that the instance accepts inbound OAuth requests from a client identified by a metadata document URL. You can fetch the client's configuration from its metadata URL or enter the details manually.

Before you begin

Role required: oauth_admin, mi_admin, admin

To fetch the configuration automatically, you need the client's CIMD metadata document URL.

About this task

You can register a CIMD client in two ways:

Fetch the configuration from the metadata URL

The instance retrieves the client's metadata document and populates the client fields for you. Use this method when the client publishes a CIMD metadata document.

Enter the configuration details manually

Provide the client fields yourself. Use this method when you want to enter or adjust the details by hand.

Each CIMD client also has a metadata sync mode that controls how the instance keeps the client's configuration current:

Live (Dynamic)

For fully trusted clients. The ServiceNow AI Platform refreshes the client configuration dynamically from the Client ID metadata. The metadata is cached and re-fetched when the cache expires (default 1 hour), not on every use.

Static (Manual)

For pre-approved clients. The ServiceNow AI Platform uses the initial configuration captured during onboarding. No automatic updates are made afterward.

Procedure

1. Navigate to All > System OAuth > CIMD Clients.
2. Select New.
3. On the What kind of OAuth application? page, select Configure a Client ID Metadata Document (CIMD) client.

   The Add a CIMD OAuth Client dialog opens.

   Figure 1. Add a CIMD OAuth Client

4. Provide the client configuration using one of the following methods:
   • Fetch from the metadata URL (recommended): In CIMD Metadata URL, enter the client's metadata document URL — for example, https://vscode.dev/oauth/client-metadata.json and select Fetch Metadata. The instance retrieves the document and populates the Client Name, Redirect URIs, Response Types, Client URI, and Logo URL fields.
   • Enter the details manually: Select Enter the details instead, and enter the client's Name, Client ID (the CIMD metadata document URL), and the remaining fields.
5. Select the Metadata Sync Mode:
   • Live: The instance fetches the latest configuration from the Client ID metadata each time the client is used. You don't maintain the Client Name, Redirect URIs, Response Types, Client URI, or Logo URI values manually.
   • Static: The instance stores the configuration captured during onboarding and makes no automatic updates. Provide the Client Name, Redirect URIs, Response Types, Client URI, or Logo URI values, because the instance doesn't refresh them automatically.
   Note:

   The registration dialog uses spec-style labels for some of these fields — Client ID (CIMD URL), Client Name, Redirect URIs, and Logo URI — while the saved record uses the labels in this table (Client ID, Name, Redirect URL, and Logo URL). These are the same fields.

   Figure 2. Add a CIMD OAuth Client

6. Optional: If the client uses localhost redirect URIs, select Localhost redirection allowed.
7. Review and complete the remaining fields, using the following descriptions.
   Note:

   • The Mode column in the following table indicates whether a field applies to both metadata sync modes or only to a specific mode.
   • Fields marked Static are entered manually; in Live mode, the instance fetches those values from the CIMD endpoint during the authorization code flow.

   Field	Required	Mode	Notes
   Name	Yes	Both	Display name for the client.
   Client ID	Yes	Both	The HTTPS CIMD metadata URL, set automatically from the URL entered at registration. This URL is the client identifier used in the OAuth flow.
   Client URI	No	Static	Client home page.
   Redirect URL	Yes	Static	Where the authorization code is returned. In Live mode, it's fetched from the CIMD endpoint during the authorization code flow. Multiple redirect URLs are supported.
   Logo URL	No	Both	Logo shown on the consent screen.
   Metadata Sync Mode	No	Both	Live (default) fetches from the CIMD endpoint. Static pins the manually entered values.
   Localhost redirection allowed	No	Both	Turn on to allow localhost redirection when the redirect URL is localhost or a loopback address.
   Active	—	Both	On by default.
   Refresh Token Lifespan	Yes	Both	Seconds; default 8,640,000.
   Access Token Lifespan	Yes	Both	Seconds; default 1,800.
   Response Types	No	Static	Supports code only; authorization code with PKCE only.
   Public Client	—	Both	Always on for CIMD clients (PKCE); read-only.
   Token Format	Yes	Both	Opaque (default) JWT
   Scope Restriction	Yes	Both	Securely scoped (default) Broadly scoped Note: For ServiceNow MCP server use cases, use Broadly Scoped.
   Cache lifespan	No	Both	Metadata cache in seconds; default 3,600.
   Auth Scopes (related list)	—	Both	Scopes granted to the client. To know more about Auth Scopes, see REST API Auth Scope.
   Generic fields
   Login URL	No	Both	Optional login URL.
   Application	—	Both	Global (read-only).
   Accessible from	—	Both	All application scopes (default).
   Comments	No	Both	Free text.

   Figure 3. CIMD Registration

8. Register the client:
   • If you fetched the metadata in the dialog, select Create.
   • If you entered the details on the form, select Submit or Update to complete the registration.

Result

The CIMD client is registered and appears in the CIMD Registered Clients list. The instance accepts inbound OAuth requests from the client, validating the request against the client's metadata each time the client initiates a flow.