> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# OAuth Scopes API

Learn about the APIs for creating, retrieving, updating and deleting OAuth scopes.

# OAuth Scopes API

This feature is only available in Essentials or Enterprise plans. To learn more, see [our pricing page](https://fusionauth.io/pricing.md).

version

Available since version `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

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create an OAuth Scope with a randomly generated Id

POST/api/application/{applicationId}/scope

OpenAPI Spec

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create an OAuth Scope with a provided unique Id

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

OpenAPI Spec

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Parameters

`applicationId`UUIDrequired

The Id of the Application.

`scopeId`UUIDoptionalDefaults to secure random UUIDImmutable

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

#### Request Body

`scope.data`Objectoptional

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

`scope.defaultConsentDetail`Stringoptional

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/customize/look-and-feel/localization.md#oauth-scope-consent-prompt)

`scope.defaultConsentMessage`Stringoptional

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/customize/look-and-feel/localization.md#oauth-scope-consent-prompt)

`scope.description`Stringoptional

A description of the OAuth Scope for internal use.

`scope.name`Stringrequired

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

`scope.required`BooleanoptionalDefaults to false

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

*Example Request JSON*

```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](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.applicationId`UUID

The unique Id of the Application.

`scope.data`Object

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

`scope.defaultConsentDetail`String

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

`scope.defaultConsentMessage`String

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

`scope.description`String

A description of the OAuth Scope for internal use.

`scope.id`UUID

The unique Id of the OAuth Scope.

`scope.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was added to the FusionAuth database.

`scope.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was updated in the FusionAuth database.

`scope.name`String

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

`scope.required`Boolean

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

*Example Response JSON*

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

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Retrieve an OAuth Scope by Id

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

OpenAPI Spec

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Parameters

`applicationId`UUIDrequired

The Id of the Application.

`scopeId`UUIDrequired

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.applicationId`UUID

The unique Id of the Application.

`scope.data`Object

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

`scope.defaultConsentDetail`String

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

`scope.defaultConsentMessage`String

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

`scope.description`String

A description of the OAuth Scope for internal use.

`scope.id`UUID

The unique Id of the OAuth Scope.

`scope.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was added to the FusionAuth database.

`scope.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was updated in the FusionAuth database.

`scope.name`String

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

`scope.required`Boolean

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

*Example Response JSON*

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

note

When updating an OAuth Scope on a universal application, a global API key is required. A tenant-scoped API key is not sufficient for this operation.

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Update an OAuth Scope by Id

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

OpenAPI Spec

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

OpenAPI Spec

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`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Parameters

`applicationId`UUIDrequired

The Id of the Application.

`scopeId`UUIDrequiredImmutable

The Id of the OAuth Scope to update.

#### Request Body

`scope.data`Objectoptional

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

`scope.defaultConsentDetail`Stringoptional

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/customize/look-and-feel/localization.md#oauth-scope-consent-prompt)

`scope.defaultConsentMessage`Stringoptional

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/customize/look-and-feel/localization.md#oauth-scope-consent-prompt)

`scope.description`Stringoptional

A description of the OAuth Scope for internal use.

`scope.required`BooleanoptionalDefaults to false

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

*Example Request JSON*

```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](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.applicationId`UUID

The unique Id of the Application.

`scope.data`Object

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

`scope.defaultConsentDetail`String

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

`scope.defaultConsentMessage`String

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

`scope.description`String

A description of the OAuth Scope for internal use.

`scope.id`UUID

The unique Id of the OAuth Scope.

`scope.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was added to the FusionAuth database.

`scope.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the OAuth Scope was updated in the FusionAuth database.

`scope.name`String

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

`scope.required`Boolean

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

*Example Response JSON*

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

note

When deleting an OAuth Scope on a universal application, a global API key is required. A tenant-scoped API key is not sufficient for this operation.

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Delete an OAuth Scope by Id

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

OpenAPI Spec

#### Request Parameters

`applicationId`UUIDrequired

The Id of the Application.

`scopeId`UUIDrequired

The Id of the OAuth Scope to delete.

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#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. |
| 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. |