CIMD Domain OAuth Scopes API

On this page

Enterprise plan required

This feature requires an Enterprise plan.

Available since 1.70.0

This page contains the APIs for managing the custom OAuth scopes of a CIMD domain. 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. Every change after that goes through the APIs on this page. The Update a CIMD Domain 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 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#

Create a CIMD Domain OAuth Scope with a randomly generated Id

POST/api/cimd/domain/{cimdDomainId}/scope

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 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.

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.

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

{
  "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 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#

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 that the OAuth Scope was added to the FusionAuth database.

scope.lastUpdateInstant

Type: Long

The instant 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

{
  "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#

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.

See 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 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.
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 that the OAuth Scope was added to the FusionAuth database.

scope.lastUpdateInstant

Type: Long

The instant 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

{
  "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#

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: application/json-patch+json
JSON Merge Patch/RFC 7396: merge-patch+json

For details, see the PATCH documentation.

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.

See 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.

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.

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

{
  "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 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.
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 that the OAuth Scope was added to the FusionAuth database.

scope.lastUpdateInstant

Type: Long

The instant 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

{
  "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#

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.

See 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 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.
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.