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

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`

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

#### Request Headers

`X-FusionAuth-TenantId`

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

*   UUID
*   required

The Id of the Application.

`scopeId`

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

*   Object
*   optional

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

`scope.defaultConsentDetail`

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

`scope.defaultConsentMessage`

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

`scope.description`

*   String
*   optional

A description of the OAuth Scope for internal use.

`scope.name`

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

*   Boolean
*   optional
*   Defaults 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}`

#### Request Headers

`X-FusionAuth-TenantId`

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

*   UUID
*   required

The Id of the Application.

`scopeId`

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

`PATCH /api/application/{applicationId}/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`

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

*   UUID
*   required

The Id of the Application.

`scopeId`

*   UUID
*   required
*   Immutable

The Id of the OAuth Scope to update.

#### Request Body

`scope.data`

*   Object
*   optional

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

`scope.defaultConsentDetail`

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

`scope.defaultConsentMessage`

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

`scope.description`

*   String
*   optional

A description of the OAuth Scope for internal use.

`scope.required`

*   Boolean
*   optional
*   Defaults 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}`

#### Request Parameters

`applicationId`

*   UUID
*   required

The Id of the Application.

`scopeId`

*   UUID
*   required

The Id of the OAuth Scope to delete.

#### Request Headers

`X-FusionAuth-TenantId`

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