Create a CIMD Domain API
On this page
This feature requires an Enterprise plan.
1.70.0
This API is used to create a CIMD domain. Specifying an Id on the URI will instruct FusionAuth to use that Id when creating the CIMD domain. Otherwise, FusionAuth will generate an Id for the CIMD domain.
Request#
Request Headers#
X-FusionAuth-TenantIdThe unique Id of the tenant used to scope this API request.
When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.
See Making an API request using a Tenant Id for additional information.
Request Parameters#
cimdDomainIdThe Id to use for the new CIMD domain, which must be unique across all Tenants. If not specified a secure random UUID will be generated.
Request Body#
domain.allowLocalhostRedirectUris Whether CIMD clients on this domain may use a localhost redirect URI, such as http://localhost:3334/callback. The URI must also appear in the client's metadata document redirect_uris. When false, FusionAuth rejects any localhost redirect URI, but still accepts loopback IP addresses such as http://127.0.0.1/callback.
RFC 8252 Section 7.3 recommends loopback IP addresses over localhost, because the name can resolve to an interface other than loopback. Enable this only for CIMD clients that require it.
domain.authorizedResourceUris The resource URIs that clients registered on this CIMD domain may request using the RFC 8707 resource parameter.
Every CIMD client must send exactly one resource parameter, and FusionAuth rejects the request with invalid_target unless it appears in this list. Clients on a domain with an empty list cannot log in.
domain.consentMode Controls whether a user is prompted to consent to the OAuth scopes requested by this domain's clients.
The possible values are:
AlwaysPrompt- Always prompt the user for consent.RememberDecision- Remember previous consents; only prompt if the choice expires or if the requested or required scopes have changed. The duration of this persisted choice is controlled by the Tenant's externalIdentifierConfiguration.rememberOAuthScopeConsentChoiceTimeToLiveInSeconds value.
FusionAuth remembers a decision separately for each client registration and resource. Changing the consent mode to AlwaysPrompt deletes every remembered decision for the domain's clients.
A value of NeverPrompt will be rejected. A CIMD client is always treated as a third-party client, and once a consent decision is skipped entirely there is no way to re-prompt the client's user.
domain.data An object that can hold any information about the CIMD domain that should be persisted.
domain.debug Whether FusionAuth writes the standard OAuth debug Event Log entries, such as the authorization code exchange, for this domain's clients. The authorization code exchange entry lists the requested resources. FusionAuth also writes a Debug entry when it creates a client registration, refreshes one after its cache expires, or adds a new resource to an existing one. FusionAuth always writes an Error entry for a failed client registration, whether or not this is enabled. It always writes an Information entry when it rate limits a registration.
domain.domain The origin that CIMD clients register from, given as scheme://host[:port]. FusionAuth normalizes this value before storing it and uses it to validate the client_id URL presented on an OAuth request.
Use the literal value * to accept registrations from any origin. A Tenant may contain either a single * domain or any number of exact-match domains, but never both.
The origin must use https, and its host must contain at least one .. A path, query string, fragment, or user info component is not permitted, and neither are IP addresses or single-label hosts such as localhost. Subdomain wildcards such as https://*.example.com are not supported.
This value cannot be changed after creation. A PUT request must still include the current value, which FusionAuth validates but does not change.
domain.gracePeriodInSeconds How long, in seconds, FusionAuth will continue to honor an expired cached metadata document when a re-fetch of that document fails. Must be greater than or equal to 0.
domain.jwtPopulateLambdaId The unique Id of the lambda used to populate the claims of the access token and Id token issued to this domain's clients. A single lambda is applied to both tokens. The lambda must be a JWT populate lambda.
domain.maxCacheTtlInSeconds The ceiling, in seconds, applied to the Cache-Control: max-age value returned when fetching a client's metadata document. When the document specifies a smaller value, that smaller value is used instead. The Expires header is not honored.
Must be at least 900, the non-configurable 15 minute minimum cache duration.
domain.name The name of the CIMD domain, used to identify it in the FusionAuth admin UI. Leave this blank to default to the value of domain.domain.
domain.providedScopePolicy.address.enabled Whether the address OAuth scope provided by FusionAuth is enabled for this CIMD domain. A disabled scope is treated as an unknown scope when a client requests it.
domain.providedScopePolicy.address.required Whether consent to the address OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.
domain.providedScopePolicy.email.enabled Whether the email OAuth scope provided by FusionAuth is enabled for this CIMD domain. A disabled scope is treated as an unknown scope when a client requests it.
domain.providedScopePolicy.email.required Whether consent to the email OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.
domain.providedScopePolicy.phone.enabled Whether the phone OAuth scope provided by FusionAuth is enabled for this CIMD domain. A disabled scope is treated as an unknown scope when a client requests it.
domain.providedScopePolicy.phone.required Whether consent to the phone OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.
domain.providedScopePolicy.profile.enabled Whether the profile OAuth scope provided by FusionAuth is enabled for this CIMD domain. A disabled scope is treated as an unknown scope when a client requests it.
domain.providedScopePolicy.profile.required Whether consent to the profile OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.
domain.registrationLambdaId The unique Id of the CIMD Client Registration Lambda used to accept, reject, or modify a client registration for this domain. The lambda must be a CIMD Client Registration lambda. When this is not set, no registration lambda runs and every client from this origin is allowed to register.
When domain.domain is *, a registration lambda is the only way to filter which clients may register.
domain.scopes The initial set of custom OAuth scopes to create on this CIMD domain. Scope names and Ids must be unique.
This field is only honored when creating a CIMD domain. Once the domain exists, manage its custom scopes using the CIMD Domain OAuth Scope APIs; any value supplied here on an update is ignored.
domain.scopes[x].data An object that can hold any information about the OAuth scope that should be persisted.
domain.scopes[x].defaultConsentDetail The default detail to display on the OAuth consent screen if one cannot be found in the theme. Learn more about setting this value using themes.
domain.scopes[x].defaultConsentMessage The default message to display on the OAuth consent screen if one cannot be found in the theme. Learn more about setting this value using themes.
domain.scopes[x].description A description of the OAuth scope for internal use.
domain.scopes[x].id The Id to use for this OAuth scope. If not specified a secure random UUID will be generated.
domain.scopes[x].name The name of the OAuth scope. This is the value that will be used to request the scope in OAuth workflows.
domain.scopes[x].required Determines if the OAuth scope is required when requested in an OAuth workflow.
domain.tenantId The Id of the Tenant this CIMD domain belongs to. When the request includes an X-FusionAuth-TenantId header or uses a Tenant-scoped API key, that Tenant is used instead of this value. One of the three must identify the Tenant.
This value cannot be changed after creation.
A CIMD domain always belongs to exactly one Tenant; there is no universal CIMD domain.
{
"domain": {
"name": "Claude",
"domain": "https://claude.ai",
"allowLocalhostRedirectUris": false,
"authorizedResourceUris": [
"https://mcp.example.com"
],
"consentMode": "AlwaysPrompt",
"debug": false,
"gracePeriodInSeconds": 300,
"maxCacheTtlInSeconds": 86400,
"providedScopePolicy": {
"address": {
"enabled": false,
"required": false
},
"email": {
"enabled": true,
"required": true
},
"phone": {
"enabled": false,
"required": false
},
"profile": {
"enabled": true,
"required": false
}
},
"registrationLambdaId": "b3a4f2d1-8c5e-4a7b-9f16-2d8e5c1a7b34"
}
}Response#
The response for this API contains the information for the CIMD domain that was created.
Response Codes| Code | Description |
|---|---|
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
Response Body#
domain.allowLocalhostRedirectUris Whether CIMD clients on this domain may use a localhost redirect URI, such as http://localhost:3334/callback. The URI must also appear in the client's metadata document redirect_uris. When false, FusionAuth rejects any localhost redirect URI, but still accepts loopback IP addresses such as http://127.0.0.1/callback.
RFC 8252 Section 7.3 recommends loopback IP addresses over localhost, because the name can resolve to an interface other than loopback. Enable this only for CIMD clients that require it.
domain.authorizedResourceUris The resource URIs that clients registered on this CIMD domain may request using the RFC 8707 resource parameter.
Every CIMD client must send exactly one resource parameter, and FusionAuth rejects the request with invalid_target unless it appears in this list. Clients on a domain with an empty list cannot log in.
domain.consentMode Controls whether a user is prompted to consent to the OAuth scopes requested by this domain's clients.
The possible values are:
AlwaysPrompt- Always prompt the user for consent.RememberDecision- Remember previous consents; only prompt if the choice expires or if the requested or required scopes have changed. The duration of this persisted choice is controlled by the Tenant's externalIdentifierConfiguration.rememberOAuthScopeConsentChoiceTimeToLiveInSeconds value.
NeverPrompt is not a valid value for a CIMD domain. CIMD clients are always treated as third-party clients, so consent can never be granted implicitly.
domain.data An object that can hold any information about the CIMD domain that should be persisted.
domain.debug Whether FusionAuth writes the standard OAuth debug Event Log entries, such as the authorization code exchange, for this domain's clients. The authorization code exchange entry lists the requested resources. FusionAuth also writes a Debug entry when it creates a client registration, refreshes one after its cache expires, or adds a new resource to an existing one. FusionAuth always writes an Error entry for a failed client registration, whether or not this is enabled. It always writes an Information entry when it rate limits a registration.
domain.domain The normalized origin that CIMD clients register from, in the form scheme://host[:port], or the literal * to accept registrations from any origin.
FusionAuth uses this value to validate the client_id URL presented on an OAuth request.
domain.gracePeriodInSeconds How long, in seconds, FusionAuth will continue to honor an expired cached metadata document when a re-fetch of that document fails.
domain.id The unique Id of the CIMD domain.
domain.insertInstant The instant that the CIMD domain was added to the FusionAuth database.
domain.jwtPopulateLambdaId The unique Id of the lambda used to populate the claims of the access token and Id token issued to this domain's clients.
domain.lastUpdateInstant The instant that the CIMD domain was last updated in the FusionAuth database.
domain.maxCacheTtlInSeconds The ceiling, in seconds, applied to the Cache-Control: max-age value returned when fetching a client's metadata document. When the document specifies a smaller value, that smaller value is used. The Expires header is not honored.
Always at least 900, the non-configurable 15 minute minimum cache duration.
domain.name The name of the CIMD domain, used to identify it in the FusionAuth admin UI. When not provided on create, this defaults to the value of domain.domain.
domain.providedScopePolicy.address.enabled Whether the address OAuth scope provided by FusionAuth is enabled for this CIMD domain. A disabled scope is treated as an unknown scope when requested.
domain.providedScopePolicy.address.required Whether consent to the address OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.
domain.providedScopePolicy.email.enabled Whether the email OAuth scope provided by FusionAuth is enabled for this CIMD domain. A disabled scope is treated as an unknown scope when requested.
domain.providedScopePolicy.email.required Whether consent to the email OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.
domain.providedScopePolicy.phone.enabled Whether the phone OAuth scope provided by FusionAuth is enabled for this CIMD domain. A disabled scope is treated as an unknown scope when requested.
domain.providedScopePolicy.phone.required Whether consent to the phone OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.
domain.providedScopePolicy.profile.enabled Whether the profile OAuth scope provided by FusionAuth is enabled for this CIMD domain. A disabled scope is treated as an unknown scope when requested.
domain.providedScopePolicy.profile.required Whether consent to the profile OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.
domain.registrationLambdaId The unique Id of the CIMD Client Registration Lambda used to accept, reject, or modify a client registration for this domain. When this is not set, no registration lambda runs.
domain.scopes The custom OAuth scopes defined on this CIMD domain. Manage these using the CIMD Domain OAuth Scope APIs.
domain.scopes[x].data An object that can hold any information about the OAuth scope that should be persisted.
domain.scopes[x].defaultConsentDetail The default detail to display on the OAuth consent screen if one cannot be found in the theme.
domain.scopes[x].defaultConsentMessage The default message to display on the OAuth consent screen if one cannot be found in the theme.
domain.scopes[x].description A description of the OAuth scope for internal use.
domain.scopes[x].id The unique Id of the OAuth scope.
domain.scopes[x].insertInstant The instant that the OAuth scope was added to the FusionAuth database.
domain.scopes[x].lastUpdateInstant The instant that the OAuth scope was updated in the FusionAuth database.
domain.scopes[x].name The name of the OAuth scope. This is the value that will be used to request the scope in OAuth workflows.
domain.scopes[x].required Determines if the OAuth scope is required when requested in an OAuth workflow.
domain.tenantId The unique Id of the Tenant that this CIMD domain belongs to.
{
"domain": {
"id": "e9fdb985-9173-4e01-9d73-ac2d60d1dc8e",
"name": "Claude",
"domain": "https://claude.ai",
"tenantId": "30663132-6464-6665-3032-326466613934",
"allowLocalhostRedirectUris": false,
"authorizedResourceUris": [
"https://mcp.example.com"
],
"consentMode": "AlwaysPrompt",
"debug": false,
"gracePeriodInSeconds": 300,
"insertInstant": 1595361142909,
"lastUpdateInstant": 1595361143101,
"maxCacheTtlInSeconds": 86400,
"providedScopePolicy": {
"address": {
"enabled": false,
"required": false
},
"email": {
"enabled": true,
"required": true
},
"phone": {
"enabled": false,
"required": false
},
"profile": {
"enabled": true,
"required": false
}
},
"registrationLambdaId": "b3a4f2d1-8c5e-4a7b-9f16-2d8e5c1a7b34",
"scopes": [
{
"id": "d7a1c3e5-2b48-4f96-8e07-5c1a9b3d6f82",
"name": "reports:read",
"defaultConsentMessage": "View your reports",
"defaultConsentDetail": "Grants read-only access to your saved reports.",
"description": "Read access to the reporting API.",
"insertInstant": 1595361143050,
"lastUpdateInstant": 1595361143050,
"required": false
}
]
}
}