---
title: "Update permission scheme"
method: PUT
path: "/rest/api/2/permissionscheme/{schemeId}"
tags: ["Permission schemes"]
---

# Update permission scheme

`PUT /rest/api/2/permissionscheme/{schemeId}`

Updates a permission scheme. Below are some important things to note when using this resource:

 *  If a permissions list is present in the request, then it is set in the permission scheme, overwriting *all existing* grants.
 *  If you want to update only the name and description, then do not send a permissions list in the request.
 *  Sending an empty list will remove all permission grants from the permission scheme.

If you want to add or delete a permission grant instead of updating the whole list, see [Create permission grant](#api-rest-api-2-permissionscheme-schemeId-permission-post) or [Delete permission scheme entity](#api-rest-api-2-permissionscheme-schemeId-permission-permissionId-delete).

See [About permission schemes and grants](../api-group-permission-schemes/#about-permission-schemes-and-grants) for more details.

**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).

## Path parameters

- `schemeId` integer, required

## Query parameters

- `expand` string

## Request body

- PermissionScheme — Details of a permission scheme.
  - `description` string — A description for the permission scheme.
  - `expand` string — The expand options available for the permission scheme.
  - `id` integer — The ID of the permission scheme.
  - `name` string, required — The name of the permission scheme. Must be unique.
  - `permissions` PermissionGrant[] — The permission scheme to create or update. See [About permission schemes and grants](../api-group-permission-schemes/#about-permission-schemes-and-grants) for more information.
    - `holder` PermissionHolder — Details of a user, group, field, or project role that holds a permission. See [Holder object](../api-group-permission-schemes/#holder-object) in *Get all permission schemes* for more information.
      - `expand` string — Expand options that include additional permission holder details in the response.
      - `parameter` string — As a group's name can change, use of `value` is recommended. The identifier associated withthe `type` value that defines the holder of the permission.
      - `type` string, required — The type of permission holder.
      - `value` string — The identifier associated with the `type` value that defines the holder of the permission.
    - `id` integer — The ID of the permission granted details.
    - `permission` string — The permission to grant. This permission can be one of the built-in permissions or a custom permission added by an app. See [Built-in permissions](../api-group-permission-schemes/#built-in-permissions) in *Get all permission schemes* for more information about the built-in permissions. See the [project permission](https://developer.atlassian.com/cloud/jira/platform/modules/project-permission/) and [global permission](https://developer.atlassian.com/cloud/jira/platform/modules/global-permission/) module documentation for more information about custom permissions.
    - `self` string, uri — The URL of the permission granted details.
  - `scope` Scope — The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO).
    - `project` ProjectDetails — Details about a project.
      - `avatarUrls` AvatarUrlsBean
        - `16x16` string, uri — The URL of the item's 16x16 pixel avatar.
        - `24x24` string, uri — The URL of the item's 24x24 pixel avatar.
        - `32x32` string, uri — The URL of the item's 32x32 pixel avatar.
        - `48x48` string, uri — The URL of the item's 48x48 pixel avatar.
      - `id` string — The ID of the project.
      - `key` string — The key of the project.
      - `name` string — The name of the project.
      - `projectCategory` UpdatedProjectCategory — A project category.
        - `description` string — The name of the project category.
        - `id` string — The ID of the project category.
        - `name` string — The description of the project category.
        - `self` string — The URL of the project category.
      - `projectTypeKey` 'software' | 'service_desk' | 'business' — The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project.
      - `self` string — The URL of the project details.
      - `simplified` boolean — Whether or not the project is simplified.
    - `type` 'PROJECT' | 'TEMPLATE' — The type of scope.
  - `self` string, uri — The URL of the permission scheme.

## Response `200`

Returned if the scheme is updated.

- PermissionScheme — Details of a permission scheme.
  - `description` string — A description for the permission scheme.
  - `expand` string — The expand options available for the permission scheme.
  - `id` integer — The ID of the permission scheme.
  - `name` string, required — The name of the permission scheme. Must be unique.
  - `permissions` PermissionGrant[] — The permission scheme to create or update. See [About permission schemes and grants](../api-group-permission-schemes/#about-permission-schemes-and-grants) for more information.
    - `holder` PermissionHolder — Details of a user, group, field, or project role that holds a permission. See [Holder object](../api-group-permission-schemes/#holder-object) in *Get all permission schemes* for more information.
      - `expand` string — Expand options that include additional permission holder details in the response.
      - `parameter` string — As a group's name can change, use of `value` is recommended. The identifier associated withthe `type` value that defines the holder of the permission.
      - `type` string, required — The type of permission holder.
      - `value` string — The identifier associated with the `type` value that defines the holder of the permission.
    - `id` integer — The ID of the permission granted details.
    - `permission` string — The permission to grant. This permission can be one of the built-in permissions or a custom permission added by an app. See [Built-in permissions](../api-group-permission-schemes/#built-in-permissions) in *Get all permission schemes* for more information about the built-in permissions. See the [project permission](https://developer.atlassian.com/cloud/jira/platform/modules/project-permission/) and [global permission](https://developer.atlassian.com/cloud/jira/platform/modules/global-permission/) module documentation for more information about custom permissions.
    - `self` string, uri — The URL of the permission granted details.
  - `scope` Scope — The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO).
    - `project` ProjectDetails — Details about a project.
      - `avatarUrls` AvatarUrlsBean
        - `16x16` string, uri — The URL of the item's 16x16 pixel avatar.
        - `24x24` string, uri — The URL of the item's 24x24 pixel avatar.
        - `32x32` string, uri — The URL of the item's 32x32 pixel avatar.
        - `48x48` string, uri — The URL of the item's 48x48 pixel avatar.
      - `id` string — The ID of the project.
      - `key` string — The key of the project.
      - `name` string — The name of the project.
      - `projectCategory` UpdatedProjectCategory — A project category.
        - `description` string — The name of the project category.
        - `id` string — The ID of the project category.
        - `name` string — The description of the project category.
        - `self` string — The URL of the project category.
      - `projectTypeKey` 'software' | 'service_desk' | 'business' — The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project.
      - `self` string — The URL of the project details.
      - `simplified` boolean — Whether or not the project is simplified.
    - `type` 'PROJECT' | 'TEMPLATE' — The type of scope.
  - `self` string, uri — The URL of the permission scheme.

## Other responses

- `401` — Returned if the authentication credentials are incorrect or missing.
- `403` — Returned if: * the user does not have the necessary permission to update permission schemes. * the Jira instance is Jira Core Free or Jira Software Free. Permission schemes cannot be updated on free plans.
- `404` — Returned if the permission scheme is not found.

---

[API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api/versions/a26541c2f8bd/schema)