Search for CIMD Domains API

On this page

Available since 1.70.0

This API is used to search for CIMD domains and may be called using the GET or POST HTTP methods. Examples of each are provided below. The POST method is provided to allow for a richer request object without worrying about exceeding the maximum length of a URL. Calling this API with either the GET or POST HTTP method will provide the same search results given the same query parameters.

Note

Unlike most CIMD domain APIs, this operation does not require the CIMD feature to be enabled on your license. You can always search your existing CIMD domain configuration.

Request#

Search for CIMD Domains

GET/api/cimd/domain/search?domain={domain}&name={name}&tenantId={tenantId}

Request Headers#

X-FusionAuth-TenantId

Type: String
Optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon other values in the request or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. 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#

domain

Type: String
Optional

The case-insensitive string to search for in the CIMD domain's domain value. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

name

Type: String
Optional

The case-insensitive string to search for in the CIMD domain name. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

numberOfResults

Type: Integer
Optional
Defaults to 25

The number of results to return from the search.

orderBy

Type: String
Optional
Defaults to name ASC

The database field to order the search results as well as an order direction.

The possible values are:

domain - the CIMD domain's domain value
id - the unique Id of the CIMD domain
insertInstant - the instant when the CIMD domain was created
name - the CIMD domain name

The order direction is optional. Possible values of the order direction are ASC or DESC. If omitted, the default sort order is ASC.

For example, to order the results by the insert instant in a descending order, use insertInstant DESC.

startRow

Type: Integer
Optional
Defaults to 0

The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.

For example, if the total search results are greater than the page size designated by numberOfResults, set this value to 25 to retrieve results 26 through 50, assuming the default page size.

tenantId

Type: UUID
Optional

Restricts the results to CIMD domains belonging to the given Tenant. This parameter will be overridden if the request contains an X-FusionAuth-TenantId header, or if the supplied API key is scoped to a specific Tenant.

Search for CIMD Domains

POST/api/cimd/domain/search

Request Headers#

X-FusionAuth-TenantId

Type: String
Optional

The unique Id of the tenant used to scope this API request.

See Making an API request using a Tenant Id for additional information.

When calling the API using a POST request you will send the search criteria in a JSON request body.

Request Body#

search.domain

Type: String
Optional

search.name

Type: String
Optional

search.numberOfResults

Type: Integer
Optional
Defaults to 25

The number of results to return from the search.

search.orderBy

Type: String
Optional
Defaults to name ASC

The database field to order the search results as well as an order direction.

The possible values are:

domain - the CIMD domain's domain value
id - the unique Id of the CIMD domain
insertInstant - the instant when the CIMD domain was created
name - the CIMD domain name

The order direction is optional. Possible values of the order direction are ASC or DESC. If omitted, the default sort order is ASC.

For example, to order the results by the insert instant in a descending order, use insertInstant DESC.

search.startRow

Type: Integer
Optional
Defaults to 0

The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.

For example, if the total search results are greater than the page size designated by numberOfResults, set this value to 25 to retrieve results 26 through 50, assuming the default page size.

search.tenantId

Type: UUID
Optional

Example JSON Request

{
  "search": {
    "domain": "claude.ai",
    "name": "Claude",
    "numberOfResults": 25,
    "orderBy": "name ASC",
    "startRow": 0,
    "tenantId": "30663132-6464-6665-3032-326466613934"
  }
}

Response#

The response for this API contains the CIMD domains matching the search criteria in paginated format.

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#

total

Type: Integer

The total number of CIMD domains matching the search criteria. Use this value along with the numberOfResults and startRow parameters to paginate the results.

domains[x].allowLocalhostRedirectUris

Type: Boolean

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.

domains[x].authorizedResourceUris

Type: Array<String>

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.

domains[x].consentMode

Type: String

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.

domains[x].data

Type: Object

An object that can hold any information about the CIMD domain that should be persisted.

domains[x].debug

Type: Boolean

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.

domains[x].domain

Type: String

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.

domains[x].gracePeriodInSeconds

Type: Integer

How long, in seconds, FusionAuth will continue to honor an expired cached metadata document when a re-fetch of that document fails.

domains[x].id

Type: UUID

The unique Id of the CIMD domain.

domains[x].insertInstant

Type: Long

The instant that the CIMD domain was added to the FusionAuth database.

domains[x].jwtPopulateLambdaId

Type: UUID

The unique Id of the lambda used to populate the claims of the access token and Id token issued to this domain's clients.

domains[x].lastUpdateInstant

Type: Long

The instant that the CIMD domain was last updated in the FusionAuth database.

domains[x].maxCacheTtlInSeconds

Type: Integer

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.

domains[x].name

Type: String

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 domains[x].domain.

domains[x].providedScopePolicy.address.enabled

Type: Boolean

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.

domains[x].providedScopePolicy.address.required

Type: Boolean

Whether consent to the address OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.

domains[x].providedScopePolicy.email.enabled

Type: Boolean

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.

domains[x].providedScopePolicy.email.required

Type: Boolean

Whether consent to the email OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.

domains[x].providedScopePolicy.phone.enabled

Type: Boolean

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.

domains[x].providedScopePolicy.phone.required

Type: Boolean

Whether consent to the phone OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.

domains[x].providedScopePolicy.profile.enabled

Type: Boolean

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.

domains[x].providedScopePolicy.profile.required

Type: Boolean

Whether consent to the profile OAuth scope provided by FusionAuth is required for this CIMD domain when present on the OAuth request.

domains[x].registrationLambdaId

Type: UUID

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.

domains[x].scopes

Type: Array

The custom OAuth scopes defined on this CIMD domain. Manage these using the CIMD Domain OAuth Scope APIs.

domains[x].scopes[x].data

Type: Object

An object that can hold any information about the OAuth scope that should be persisted.

domains[x].scopes[x].defaultConsentDetail

Type: String

The default detail to display on the OAuth consent screen if one cannot be found in the theme.

domains[x].scopes[x].defaultConsentMessage

Type: String

The default message to display on the OAuth consent screen if one cannot be found in the theme.

domains[x].scopes[x].description

Type: String

A description of the OAuth scope for internal use.

domains[x].scopes[x].id

Type: UUID

The unique Id of the OAuth scope.

domains[x].scopes[x].insertInstant

Type: Long

The instant that the OAuth scope was added to the FusionAuth database.

domains[x].scopes[x].lastUpdateInstant

Type: Long

The instant that the OAuth scope was updated in the FusionAuth database.

domains[x].scopes[x].name

Type: String

The name of the OAuth scope. This is the value that will be used to request the scope in OAuth workflows.

domains[x].scopes[x].required

Type: Boolean

Determines if the OAuth scope is required when requested in an OAuth workflow.

domains[x].tenantId

Type: UUID

The unique Id of the Tenant that this CIMD domain belongs to.

Example JSON Response

{
  "domains": [
    {
      "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": []
    }
  ],
  "total": 1
}