# CIMD Domain OAuth Scopes API Learn about the APIs for creating, retrieving, updating and deleting the custom OAuth scopes of a CIMD domain. > For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt) > **PLAN:** This feature requires [an Enterprise plan](https://fusionauth.io/docs/get-started/core-concepts/plans-features.md#enterprise-features). Available since `1.70.0` This page contains the APIs for managing the custom OAuth scopes of a [CIMD domain](https://fusionauth.io/docs/get-started/core-concepts/types/cimd-domains.md). These scopes are requestable by any client that registers through the domain, in addition to the standard OpenID Connect scopes enabled by the domain's **providedScopePolicy**. A CIMD domain's initial scopes may be supplied when [creating the domain](https://fusionauth.io/docs/apis/cimd-domains/create-a-cimd-domain.md). Every change after that goes through the APIs on this page. The [Update a CIMD Domain](https://fusionauth.io/docs/apis/cimd-domains/update-a-cimd-domain.md) API ignores the **domain.scopes** field. Note There is no API to retrieve all of a CIMD domain's scopes as a collection. The full `scopes` list is returned on the domain itself by the [Retrieve a CIMD Domain](https://fusionauth.io/docs/apis/cimd-domains/retrieve-a-cimd-domain.md) API. Every API on this page returns a `400` with an `[invalid]domainId` error when the CIMD domain doesn't exist or belongs to a different Tenant. A `404` means the domain exists but the OAuth scope doesn't. ## Create a CIMD Domain OAuth Scope This API is used to create a custom OAuth scope for a CIMD domain. Specifying an Id on the URI will instruct FusionAuth to use that Id when creating the OAuth scope. Otherwise, FusionAuth will generate an Id for the OAuth scope. ### Request [API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Create a CIMD Domain OAuth Scope with a randomly generated Id `POST /api/cimd/domain/{cimdDomainId}/scope` [API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Create a CIMD Domain OAuth Scope with a provided unique Id `POST /api/cimd/domain/{cimdDomainId}/scope/{scopeId}` #### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information. #### Request Parameters `cimdDomainId` * Type: `UUID` * Required The Id of the CIMD domain. `scopeId` * Type: `UUID` * Optional * Defaults to `secure random UUID` * Immutable The Id to use for the new OAuth scope. If not specified a secure random UUID will be generated. ##### Request Body `scope.data` * Type: `Object` * Optional An object that can hold any information about the OAuth Scope that should be persisted. `scope.defaultConsentDetail` * Type: `String` * Optional 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.](https://fusionauth.io/docs/theme/localization.md#oauth-scope-consent-prompt) `scope.defaultConsentMessage` * Type: `String` * Optional 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.](https://fusionauth.io/docs/theme/localization.md#oauth-scope-consent-prompt) `scope.description` * Type: `String` * Optional A description of the OAuth Scope for internal use. `scope.name` * Type: `String` * Required The name of the OAuth Scope. This is the value that will be used to request the scope in OAuth workflows. `scope.required` * Type: `Boolean` * Optional * Defaults to `false` Determines if the OAuth Scope is required when requested in an OAuth workflow. Example Request JSON ```json { "scope": { "name": "reports:read", "defaultConsentDetail": "Grants read-only access to your saved reports.", "defaultConsentMessage": "View your reports", "description": "Read access to the reporting API.", "required": false } } ``` ### Response The response for this API contains the information for the OAuth scope 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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). | | 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 `scope.domainId` * Type: `UUID` The unique Id of the CIMD domain. `scope.data` * Type: `Object` An object that can hold any information about the OAuth Scope that should be persisted. `scope.defaultConsentDetail` * Type: `String` The default detail to display on the OAuth consent screen if one cannot be found in the theme. `scope.defaultConsentMessage` * Type: `String` The default message to display on the OAuth consent screen if one cannot be found in the theme. `scope.description` * Type: `String` A description of the OAuth Scope for internal use. `scope.id` * Type: `UUID` The unique Id of the OAuth Scope. `scope.insertInstant` * Type: `Long` The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was added to the FusionAuth database. `scope.lastUpdateInstant` * Type: `Long` The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was updated in the FusionAuth database. `scope.name` * Type: `String` The name of the OAuth Scope. This is the value that will be used to request the scope in OAuth workflows. `scope.required` * Type: `Boolean` Determines if the OAuth Scope is required when requested in an OAuth workflow. Example Response JSON ```json { "scope": { "id": "d7a1c3e5-2b48-4f96-8e07-5c1a9b3d6f82", "domainId": "e9fdb985-9173-4e01-9d73-ac2d60d1dc8e", "name": "reports:read", "defaultConsentDetail": "Grants read-only access to your saved reports.", "defaultConsentMessage": "View your reports", "description": "Read access to the reporting API.", "insertInstant": 1595361143050, "lastUpdateInstant": 1595361143050, "required": false } } ``` ## Retrieve a CIMD Domain OAuth Scope This API is used to retrieve a single custom OAuth scope for a CIMD domain by unique Id. Note Unlike the other CIMD domain OAuth scope APIs, this operation does not require the CIMD feature to be enabled on your license. You can always read your existing scope configuration. ### Request [API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Retrieve a CIMD Domain OAuth Scope by Id `GET /api/cimd/domain/{cimdDomainId}/scope/{scopeId}` #### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information. #### Request Parameters `cimdDomainId` * Type: `UUID` * Required The Id of the CIMD domain. `scopeId` * Type: `UUID` * Required The Id of the OAuth scope to retrieve. ### Response The response for this API contains a single OAuth scope. *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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). | | 404 | The object you requested doesn't exist. The response will be empty. | | 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 `scope.domainId` * Type: `UUID` The unique Id of the CIMD domain. `scope.data` * Type: `Object` An object that can hold any information about the OAuth Scope that should be persisted. `scope.defaultConsentDetail` * Type: `String` The default detail to display on the OAuth consent screen if one cannot be found in the theme. `scope.defaultConsentMessage` * Type: `String` The default message to display on the OAuth consent screen if one cannot be found in the theme. `scope.description` * Type: `String` A description of the OAuth Scope for internal use. `scope.id` * Type: `UUID` The unique Id of the OAuth Scope. `scope.insertInstant` * Type: `Long` The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was added to the FusionAuth database. `scope.lastUpdateInstant` * Type: `Long` The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was updated in the FusionAuth database. `scope.name` * Type: `String` The name of the OAuth Scope. This is the value that will be used to request the scope in OAuth workflows. `scope.required` * Type: `Boolean` Determines if the OAuth Scope is required when requested in an OAuth workflow. Example Response JSON ```json { "scope": { "id": "d7a1c3e5-2b48-4f96-8e07-5c1a9b3d6f82", "domainId": "e9fdb985-9173-4e01-9d73-ac2d60d1dc8e", "name": "reports:read", "defaultConsentDetail": "Grants read-only access to your saved reports.", "defaultConsentMessage": "View your reports", "description": "Read access to the reporting API.", "insertInstant": 1595361143050, "lastUpdateInstant": 1595361143050, "required": false } } ``` ## Update a CIMD Domain OAuth Scope This API is used to update an existing OAuth Scope. You must specify all of the properties of the OAuth Scope when calling this API with the `PUT` HTTP method. When used with `PUT`, this API doesn't merge the existing OAuth Scope and your new data. It replaces the existing OAuth Scope with your new data. Utilize the `PATCH` HTTP method to send specific changes to merge into an existing OAuth Scope. ### Request [API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Update a CIMD Domain OAuth Scope by Id `PUT /api/cimd/domain/{cimdDomainId}/scope/{scopeId}` `PATCH /api/cimd/domain/{cimdDomainId}/scope/{scopeId}` Note For backward compatibility, the `PATCH` method accepts the same media type (specified by a `Content-Type` of `application/json`) and body as the `PUT` request. You can also use the following media types for different behavior: * [JSON Patch/RFC 6902](https://www.rfc-editor.org/rfc/rfc6902): `application/json-patch+json` * [JSON Merge Patch/RFC 7396](https://www.rfc-editor.org/rfc/rfc7396): `merge-patch+json` For details, see the [PATCH documentation](https://fusionauth.io/docs/apis.md#the-patch-http-method). Using a media type of `application/json` merges the provided request parameters into the existing object. As a result, all parameters are optional with `PATCH`: only provide the values you want to change. To remove a value, provide a `null` value. Patching an `Array` appends all values in the new list to the old list. #### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information. #### Request Parameters `cimdDomainId` * Type: `UUID` * Required The Id of the CIMD domain. `scopeId` * Type: `UUID` * Required The Id of the OAuth scope to update. ##### Request Body `scope.data` * Type: `Object` * Optional An object that can hold any information about the OAuth Scope that should be persisted. `scope.defaultConsentDetail` * Type: `String` * Optional 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.](https://fusionauth.io/docs/theme/localization.md#oauth-scope-consent-prompt) `scope.defaultConsentMessage` * Type: `String` * Optional 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.](https://fusionauth.io/docs/theme/localization.md#oauth-scope-consent-prompt) `scope.description` * Type: `String` * Optional A description of the OAuth Scope for internal use. `scope.required` * Type: `Boolean` * Optional * Defaults to `false` Determines if the OAuth Scope is required when requested in an OAuth workflow. Example Request JSON ```json { "scope": { "defaultConsentDetail": "Grants read and write access to your saved reports.", "defaultConsentMessage": "Manage your reports", "description": "Read and write access to the reporting API.", "required": true } } ``` ### Response The response for this API contains the new information for the OAuth scope that was updated. *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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). | | 404 | The object you are trying to update doesn't exist. The response will be empty. | | 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 `scope.domainId` * Type: `UUID` The unique Id of the CIMD domain. `scope.data` * Type: `Object` An object that can hold any information about the OAuth Scope that should be persisted. `scope.defaultConsentDetail` * Type: `String` The default detail to display on the OAuth consent screen if one cannot be found in the theme. `scope.defaultConsentMessage` * Type: `String` The default message to display on the OAuth consent screen if one cannot be found in the theme. `scope.description` * Type: `String` A description of the OAuth Scope for internal use. `scope.id` * Type: `UUID` The unique Id of the OAuth Scope. `scope.insertInstant` * Type: `Long` The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was added to the FusionAuth database. `scope.lastUpdateInstant` * Type: `Long` The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was updated in the FusionAuth database. `scope.name` * Type: `String` The name of the OAuth Scope. This is the value that will be used to request the scope in OAuth workflows. `scope.required` * Type: `Boolean` Determines if the OAuth Scope is required when requested in an OAuth workflow. Example Response JSON ```json { "scope": { "id": "d7a1c3e5-2b48-4f96-8e07-5c1a9b3d6f82", "domainId": "e9fdb985-9173-4e01-9d73-ac2d60d1dc8e", "name": "reports:read", "defaultConsentDetail": "Grants read and write access to your saved reports.", "defaultConsentMessage": "Manage your reports", "description": "Read and write access to the reporting API.", "insertInstant": 1595361143050, "lastUpdateInstant": 1595361150422, "required": true } } ``` ## Delete a CIMD Domain OAuth Scope This API is used to permanently delete a custom OAuth scope from a CIMD domain. You must specify the Id of the CIMD domain and the Id of the OAuth scope on the URI. Caution This is a hard delete and cannot be reversed. OAuth workflows that continue to request the deleted scope will fail, because a CIMD domain always rejects unknown scopes. ### Request [API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication) Delete a CIMD Domain OAuth Scope by Id `DELETE /api/cimd/domain/{cimdDomainId}/scope/{scopeId}` #### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information. #### Request Parameters `cimdDomainId` * Type: `UUID` * Required The Id of the CIMD domain. `scopeId` * Type: `UUID` * Required The Id of the OAuth scope to delete. ### Response This API does not return a JSON response body. *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. | | 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). | | 404 | The object you requested doesn't exist. The response will be empty. | | 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. | --- ## Other pages in Apis > For the full index of this section, see [Apis](https://fusionauth.io/docs/llms-apis.txt). - [User Action API](https://fusionauth.io/docs/apis/actioning-users.md): Learn about the APIs for invoking a User Action on a User. - [API Keys API](https://fusionauth.io/docs/apis/api-keys.md): Learn about the APIs for creating, retrieving, updating and deleting API Keys. - [Application API](https://fusionauth.io/docs/apis/applications.md): Learn about the APIs for creating, retrieving, updating and deleting Applications. - [Audit Log API](https://fusionauth.io/docs/apis/audit-logs.md): Learn about the APIs for adding entries to, searching, and exporting the audit log. - [Authenticate with our APIs](https://fusionauth.io/docs/apis/authentication.md): Learn how the FusionAuth APIs authenticate requests. - [CIMD Client Registration API](https://fusionauth.io/docs/apis/cimd-client-registrations.md): Learn about the APIs for retrieving, searching for, and deleting CIMD client registrations. - [CIMD Domain API](https://fusionauth.io/docs/apis/cimd-domains.md): Learn about the APIs for creating, retrieving, updating and deleting CIMD domains. - [Configure CORS](https://fusionauth.io/docs/apis/configure-cors.md): How to set up and use the FusionAuth API Explorer. - [Connector API](https://fusionauth.io/docs/apis/connectors.md): Learn about the APIs for creating, retrieving, updating and deleting identity providers. - [Consent API](https://fusionauth.io/docs/apis/consents.md): Learn about the APIs for creating, retrieving, updating and deleting consents. - [Email API](https://fusionauth.io/docs/apis/emails.md): Learn about the APIs for creating, retrieving, updating and deleting email templates as well as sending emails to users. - [Entity API](https://fusionauth.io/docs/apis/entities.md): Learn about the APIs for creating, retrieving, updating and deleting entities and entity types. - [Error Responses](https://fusionauth.io/docs/apis/errors.md): Learn about the error response that is returned from FusionAuth APIs. - [Event Log API](https://fusionauth.io/docs/apis/event-logs.md): Learn about the APIs for searching and retrieving event logs. - [Family API](https://fusionauth.io/docs/apis/families.md): Learn about the APIs for creating, retrieving, updating and deleting families. - [Group API](https://fusionauth.io/docs/apis/groups.md): Learn about the APIs for creating, retrieving, updating and deleting groups. - [Hosted Backend API](https://fusionauth.io/docs/apis/hosted-backend.md): Learn about the APIs that you to perform OAuth2 Authorization Code Flow login, logout, and refresh for applications. - [Identity Provider API](https://fusionauth.io/docs/apis/identity-providers.md): Learn about the APIs for creating, retrieving, updating and deleting identity providers. - [Identity Verify API](https://fusionauth.io/docs/apis/identity-verify.md): Learn about the APIs for starting, sending, and completing identity verification. - [Integration API](https://fusionauth.io/docs/apis/integrations.md): Learn about the APIs for retrieving and updating integrations. - [IP Access Control List API](https://fusionauth.io/docs/apis/ip-acl.md): Learn about the APIs for creating, retrieving, updating and deleting IP Access Control Lists. - [JWTs & Refresh Token API](https://fusionauth.io/docs/apis/jwt.md): Learn about the APIs that allow you to manage Refresh Tokens, verify Access Tokens and retrieve public keys used for verifying JWT signatures. - [Key API](https://fusionauth.io/docs/apis/keys.md): Learn about the APIs for generating, importing, retrieving, updating and deleting keys. - [Lambda API](https://fusionauth.io/docs/apis/lambdas.md): Learn about the APIs for creating, retrieving, updating and deleting lambdas. - [Login API](https://fusionauth.io/docs/apis/login.md): API documentation for the FusionAuth Login API. - [Message Template API](https://fusionauth.io/docs/apis/message-templates.md): Learn about the APIs for creating, retrieving, updating and deleting message templates. - [Messenger API](https://fusionauth.io/docs/apis/messengers.md): Learn about the APIs for creating, retrieving, updating and deleting messengers. - [OAuth2 API](https://fusionauth.io/docs/apis/oauth.md): This page details FusionAuth's OAuth2 endpoints. Learn about the Authorization Code grant, `Implicit` grant, and other OAuth2 grants. - [OpenAPI Specification](https://fusionauth.io/docs/apis/openapi.md): Learn about the FusionAuth OpenAPI Specification, which allows you to use OpenAPI tooling to interact with FusionAuth. - [Passwordless API](https://fusionauth.io/docs/apis/passwordless.md): Learn about the APIs for one-time password authentication. - [Reactor API](https://fusionauth.io/docs/apis/reactor.md): Learn about the APIs for activating, deactivating, and retrieving the status of a FusionAuth Reactor license. - [User Registration API](https://fusionauth.io/docs/apis/registrations.md): Learn about the APIs for creating, retrieving, updating and deleting User Registrations. - [Report API](https://fusionauth.io/docs/apis/reports.md): Learn about the APIs for retrieving reports from FusionAuth. - [SCIM API](https://fusionauth.io/docs/apis/scim.md): Learn about the APIs for provisioning SCIM Resources in FusionAuth using a SCIM Client. - [OAuth Scopes API](https://fusionauth.io/docs/apis/scopes.md): Learn about the APIs for creating, retrieving, updating and deleting OAuth scopes. - [System API](https://fusionauth.io/docs/apis/system.md): Learn about the APIs for retrieving and updating the system configuration. - [Tenant Manager API](https://fusionauth.io/docs/apis/tenant-manager.md): Learn about the APIs for retrieving and updating Tenant Manager configuration. - [Tenants API](https://fusionauth.io/docs/apis/tenants.md): Learn about the APIs for creating, retrieving, updating and deleting tenants. - [Multi-Factor API](https://fusionauth.io/docs/apis/two-factor.md): Learn about the APIs for enabling and disabling multi-factor authentication for users. - [User Action Reason API](https://fusionauth.io/docs/apis/user-action-reasons.md): Learn about the APIs for creating, retrieving, updating and deleting user action reasons. - [Manage User Action API](https://fusionauth.io/docs/apis/user-actions.md): Learn about the APIs for creating, retrieving, updating and deleting user actions. - [User Comment API](https://fusionauth.io/docs/apis/user-comments.md): Learn about the APIs for creating and retrieving comments on users. - [User API](https://fusionauth.io/docs/apis/users.md): Learn how to integrate with the FusionAuth User API. This documentation provides a comprehensive reference for managing users. - [WebAuthn API](https://fusionauth.io/docs/apis/webauthn.md): Learn about the APIs for starting and completing WebAuthn ceremonies and retrieving, importing and deleting WebAuthn passkeys. - [Webhook Event Log API](https://fusionauth.io/docs/apis/webhook-event-logs.md): Learn about the APIs for searching and retrieving webhook event and attempt logs. - [Webhook API](https://fusionauth.io/docs/apis/webhooks.md): Learn about the APIs for creating, retrieving, updating and deleting Webhooks.