OAuth Scopes

This feature is only available in an Essentials or Enterprise plan. Please visit our pricing page to learn more.

Overview

This API has been available since 1.50.0

This page contains the APIs for managing the OAuth Scopes of an Application.

Create an OAuth Scope

This API is used to create an OAuth Scope for an Application. 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 an OAuth Scope with a randomly generated Id

POST /api/application/{applicationId}/scope

Create an OAuth Scope with a provided unique Id

POST /api/application/{applicationId}/scope/{scopeId}

Request Headers

X-FusionAuth-TenantIdString

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 the request parameters 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

applicationIdUUIDrequired

The Id of the Application.

scopeIdUUIDDefaults to secure random UUID

The Id to use for the new OAuth Scope. If not specified a secure random UUID will be generated.

Request Body

scope.dataObject

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

scope.defaultConsentDetailString

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

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

A description of the OAuth Scope for internal use.

scope.nameStringrequired

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

scope.requiredBooleanDefaults to false

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

Example Request JSON

{
  "scope": {
    "data": {
      "addedBy": "richard"
    },
    "defaultConsentDetail": "This will provide the requesting application read-only access to your data",
    "defaultConsentMessage": "View your data",
    "description": "Provides an application read-only access to a user's data",
    "name": "data:read",
    "required": true
  }
}

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

The unique Id of the Application.

scope.dataObject

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

scope.defaultConsentDetailString

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

scope.defaultConsentMessageString

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

scope.descriptionString

A description of the OAuth Scope for internal use.

scope.idUUID

The unique Id of the OAuth Scope.

scope.insertInstantLong

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

scope.lastUpdateInstantLong

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

scope.nameString

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

scope.requiredBoolean

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

Example Response JSON

{
  "scope": {
    "applicationId": "8c9f82c8-0926-4c6c-b8be-1bcface5b378",
    "data": {
      "addedBy": "richard"
    },
    "defaultConsentDetail": "This will provide the requesting application read-only access to your data",
    "defaultConsentMessage": "View your data",
    "description": "Provides an application read-only access to a user's data",
    "id": "f32b777a-8cc4-4233-afcf-d4c42d3ca488",
    "insertInstant": 1712268302394,
    "lastUpdateInstant": 1712268302394,
    "name": "data:read",
    "required": true
  }
}

Retrieve an OAuth Scope

This API is used to retrieve a single OAuth Scope for an Application by unique Id.

Request

Retrieve an OAuth Scope by Id

GET /api/application/{applicationId}/scope/{scopeId}

Request Headers

X-FusionAuth-TenantIdString

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

applicationIdUUIDrequired

The Id of the Application.

scopeIdUUIDrequired

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

The unique Id of the Application.

scope.dataObject

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

scope.defaultConsentDetailString

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

scope.defaultConsentMessageString

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

scope.descriptionString

A description of the OAuth Scope for internal use.

scope.idUUID

The unique Id of the OAuth Scope.

scope.insertInstantLong

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

scope.lastUpdateInstantLong

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

scope.nameString

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

scope.requiredBoolean

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

Example Response JSON

{
  "scope": {
    "applicationId": "8c9f82c8-0926-4c6c-b8be-1bcface5b378",
    "data": {
      "addedBy": "richard"
    },
    "defaultConsentDetail": "This will provide the requesting application read-only access to your data",
    "defaultConsentMessage": "View your data",
    "description": "Provides an application read-only access to a user's data",
    "id": "f32b777a-8cc4-4233-afcf-d4c42d3ca488",
    "insertInstant": 1712268302394,
    "lastUpdateInstant": 1712268302394,
    "name": "data:read",
    "required": true
  }
}

Update an 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 an OAuth Scope by Id

PUT /api/application/{applicationId}/scope/{scopeId}

PATCH /api/application/{applicationId}/scope/{scopeId}

When using the PATCH method, you can either use the same request body documentation that is provided for the PUT request for backward compatibility. Or you may use either JSON Patch/RFC 6902] or JSON Merge Patch/RFC 7396. See the PATCH documentation for more information.

When using the PATCH method with a Content-Type of application/json the provided request parameters will be merged into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A null value can be used to remove a value. Patching an Array will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.

Request Headers

X-FusionAuth-TenantIdString

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

applicationIdUUIDrequired

The Id of the Application.

scopeIdUUIDrequired

The Id of the OAuth Scope to update.

Request Body

scope.dataObject

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

scope.defaultConsentDetailString

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

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

A description of the OAuth Scope for internal use.

scope.requiredBooleanDefaults to false

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

Example Request JSON

{
  "scope": {
    "data": {
      "addedBy": "richard",
      "internal": false
    },
    "defaultConsentDetail": "This scope will provide the requesting application read-only access to your data",
    "defaultConsentMessage": "View data",
    "description": "Provides an application read access to a user's data",
    "required": false
  }
}

Response

The response for this API contains the 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.applicationIdUUID

The unique Id of the Application.

scope.dataObject

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

scope.defaultConsentDetailString

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

scope.defaultConsentMessageString

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

scope.descriptionString

A description of the OAuth Scope for internal use.

scope.idUUID

The unique Id of the OAuth Scope.

scope.insertInstantLong

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

scope.lastUpdateInstantLong

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

scope.nameString

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

scope.requiredBoolean

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

Example Response JSON

{
  "scope": {
    "applicationId": "8c9f82c8-0926-4c6c-b8be-1bcface5b378",
    "data": {
      "addedBy": "richard",
      "internal": false
    },
    "defaultConsentDetail": "This scope will provide the requesting application read-only access to your data",
    "defaultConsentMessage": "View data",
    "description": "Provides an application read access to a user's data",
    "id": "f32b777a-8cc4-4233-afcf-d4c42d3ca488",
    "insertInstant": 1712268302394,
    "lastUpdateInstant": 1712298702394,
    "name": "data:read",
    "required": false
  }
}

Delete an OAuth Scope

This API is used to permanently delete an OAuth Scope.

Request

Delete an OAuth Scope by Id

DELETE /api/application/{applicationId}/scope/{scopeId}

Request Parameters

applicationIdUUIDrequired

The Id of the Application.

scopeIdUUIDrequired

The Id of the OAuth Scope to delete.

Request Headers

X-FusionAuth-TenantIdString

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

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

Response

This API does not return a JSON response body.

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.

Results

Recent

OAuth Scopes

Overview

Create an OAuth Scope

Request

Request Headers

Request Parameters

Request Body

Response

Response Body

Retrieve an OAuth Scope

Request

Request Headers

Request Parameters

Response

Response Body

Update an OAuth Scope

Request

Request Headers

Request Parameters

Request Body

Response

Response Body

Delete an OAuth Scope

Request

Request Parameters

Request Headers

Response

Results

Recent