• Announcement banner
  • App data policies (EAP)
  • Application roles
  • Audit records
  • Avatars
  • Classification levels
  • Dashboards
  • Filters
  • Filter sharing
  • Group and user picker
  • Groups
  • Issues
  • UI modifications (apps)
  • Issue attachments
  • Issue comments
  • Issue comment properties
  • Issue fields
  • Issue field configurations
  • Issue custom field contexts
  • Issue custom field options
  • Issue custom field options (apps)
  • Issue custom field values (apps)
  • Issue custom field configuration (apps)
  • Issue navigator settings
  • Issue notification schemes
  • Issue priorities
  • Issue properties
  • Issue resolutions
  • Issue security level
  • Issue security schemes
  • Issue types
  • Issue type schemes
  • Issue type screen schemes
  • Issue type properties
  • Issue votes
  • Issue watchers
  • Issue worklogs
  • Issue worklog properties
  • Jira expressions
  • Jira settings
  • JQL
  • JQL functions (apps)
  • Labels
  • License metrics
  • Myself
  • Permissions
  • Permission schemes
  • Projects
  • Project avatars
  • Project categories
  • Project classification levels
  • Project components
  • Project email
  • Project features
  • Project key and name validation
  • Project permission schemes
  • Project properties
  • Project roles
  • Project role actors
  • Project types
  • Project versions
  • Screens
  • Screen tabs
  • Screen tab fields
  • Screen schemes
  • Server info
  • Status
  • Tasks
  • Time tracking
  • Users
  • User properties
  • Webhooks
  • Workflows
  • Workflow transition rules
  • Workflow schemes
  • Workflow scheme project associations
  • Workflow scheme drafts
  • Workflow statuses
  • Workflow status categories
  • Workflow transition properties
  • App properties
  • Dynamic modules
  • App migration
  • Service Registry
Cloud
Jira Cloud platform / Reference / REST API v2

Permission schemes

Postman Collection
OpenAPI
GET

Get all permission schemes

Returns all permission schemes.

About permission schemes and grants

A permission scheme is a collection of permission grants. A permission grant consists of a holder and a permission.

Holder object

The holder object contains information about the user or group being granted the permission. For example, the Administer projects permission is granted to a group named Teams in space administrators. In this case, the type is "type": "group", and the parameter is the group name, "parameter": "Teams in space administrators" and the value is group ID, "value": "ca85fac0-d974-40ca-a615-7af99c48d24f".

The holder object is defined by the following properties:

  • type Identifies the user or group (see the list of types below).
  • parameter As a group's name can change, use of value is recommended. The value of this property depends on the type. For example, if the type is a group, then you need to specify the group name.
  • value The value of this property depends on the type. If the type is a group, then you need to specify the group ID. For other type it has the same value as parameter

The following types are available. The expected values for parameter and value are given in parentheses (some types may not have a parameter or value):

Built-in permissions

The built-in Jira permissions are listed below. Apps can also define custom permissions. See the project permission and global permission module documentation for more information.

Project permissions

  • ADMINISTER_PROJECTS
  • BROWSE_PROJECTS
  • MANAGE_SPRINTS_PERMISSION (Jira Software only)
  • SERVICEDESK_AGENT (Jira Service Desk only)
  • VIEW_DEV_TOOLS (Jira Software only)
  • VIEW_READONLY_WORKFLOW

Issue permissions

  • ASSIGNABLE_USER
  • ASSIGN_ISSUES
  • CLOSE_ISSUES
  • CREATE_ISSUES
  • DELETE_ISSUES
  • EDIT_ISSUES
  • LINK_ISSUES
  • MODIFY_REPORTER
  • MOVE_ISSUES
  • RESOLVE_ISSUES
  • SCHEDULE_ISSUES
  • SET_ISSUE_SECURITY
  • TRANSITION_ISSUES

Voters and watchers permissions

  • MANAGE_WATCHERS
  • VIEW_VOTERS_AND_WATCHERS

Comments permissions

  • ADD_COMMENTS
  • DELETE_ALL_COMMENTS
  • DELETE_OWN_COMMENTS
  • EDIT_ALL_COMMENTS
  • EDIT_OWN_COMMENTS

Attachments permissions

  • CREATE_ATTACHMENTS
  • DELETE_ALL_ATTACHMENTS
  • DELETE_OWN_ATTACHMENTS

Time tracking permissions

  • DELETE_ALL_WORKLOGS
  • DELETE_OWN_WORKLOGS
  • EDIT_ALL_WORKLOGS
  • EDIT_OWN_WORKLOGS
  • WORK_ON_ISSUES

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work
Granular:read:application-role:jira, read:field:jira, read:group:jira, read:permission-scheme:jira, read:permission:jira ...(Show more)

Request

Query parameters

expand

string

Responses

Returned if the request is successful.

application/json

PermissionSchemes

List of all permission schemes.

GET/rest/api/2/permissionscheme
1 2 3 4 5 6 7 8 9 10 11 12 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().requestJira(route`/rest/api/2/permissionscheme`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 { "permissionSchemes": [ { "description": "description", "id": 10000, "name": "Example permission scheme", "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/10000" } ] }
POST

Create permission scheme

Creates a new permission scheme. You can create a permission scheme with or without defining a set of permission grants.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredADMIN

ClassicRECOMMENDED:manage:jira-configuration
Granular:write:permission-scheme:jira, read:application-role:jira, read:field:jira, read:group:jira, read:permission-scheme:jira ...(Show more)

Request

Query parameters

expand

string

Request bodyapplication/json

The permission scheme to create.

description

string

name

string

Required
permissions

array<PermissionGrant>

scope

Scope

Additional Properties

any

Responses

Returned if the permission scheme is created.

application/json

PermissionScheme

Details of a permission scheme.

POST/rest/api/2/permissionscheme
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; var bodyData = `{ "description": "description", "name": "Example permission scheme", "permissions": [ { "holder": { "parameter": "jira-core-users", "type": "group", "value": "ca85fac0-d974-40ca-a615-7af99c48d24f" }, "permission": "ADMINISTER_PROJECTS" } ] }`; const response = await api.asUser().requestJira(route`/rest/api/2/permissionscheme`, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: bodyData }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
201Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 { "description": "description", "id": 10000, "name": "Example permission scheme", "permissions": [ { "holder": { "expand": "group", "parameter": "jira-core-users", "type": "group", "value": "ca85fac0-d974-40ca-a615-7af99c48d24f" }, "id": 10000, "permission": "ADMINISTER_PROJECTS", "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/permission/10000" } ], "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/10000" }
GET

Get permission scheme

Returns a permission scheme.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work
Granular:read:application-role:jira, read:field:jira, read:group:jira, read:permission-scheme:jira, read:permission:jira ...(Show more)

Request

Path parameters

schemeId

integer

Required

Query parameters

expand

string

Responses

Returned if the request is successful.

application/json

PermissionScheme

Details of a permission scheme.

GET/rest/api/2/permissionscheme/{schemeId}
1 2 3 4 5 6 7 8 9 10 11 12 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().requestJira(route`/rest/api/2/permissionscheme/{schemeId}`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 { "description": "description", "id": 10000, "name": "Example permission scheme", "permissions": [ { "holder": { "expand": "group", "parameter": "jira-core-users", "type": "group", "value": "ca85fac0-d974-40ca-a615-7af99c48d24f" }, "id": 10000, "permission": "ADMINISTER_PROJECTS", "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/permission/10000" } ], "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/10000" }
PUT

Update permission scheme

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 or Delete permission scheme entity.

See About permission schemes and grants for more details.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredADMIN

ClassicRECOMMENDED:manage:jira-configuration
Granular:write:permission-scheme:jira, read:application-role:jira, read:field:jira, read:group:jira, read:permission-scheme:jira ...(Show more)

Request

Path parameters

schemeId

integer

Required

Query parameters

expand

string

Request bodyapplication/json

description

string

name

string

Required
permissions

array<PermissionGrant>

scope

Scope

Additional Properties

any

Responses

Returned if the scheme is updated.

application/json

PermissionScheme

Details of a permission scheme.

PUT/rest/api/2/permissionscheme/{schemeId}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; var bodyData = `{ "description": "description", "name": "Example permission scheme", "permissions": [ { "holder": { "parameter": "jira-core-users", "type": "group", "value": "ca85fac0-d974-40ca-a615-7af99c48d24f" }, "permission": "ADMINISTER_PROJECTS" } ] }`; const response = await api.asUser().requestJira(route`/rest/api/2/permissionscheme/{schemeId}`, { method: 'PUT', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: bodyData }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 { "description": "description", "id": 10000, "name": "Example permission scheme", "permissions": [ { "holder": { "expand": "group", "parameter": "jira-core-users", "type": "group", "value": "ca85fac0-d974-40ca-a615-7af99c48d24f" }, "id": 10000, "permission": "ADMINISTER_PROJECTS", "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/permission/10000" } ], "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/10000" }
DEL

Delete permission scheme

Deletes a permission scheme.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredADMIN

ClassicRECOMMENDED:manage:jira-configuration
Granular:delete:permission-scheme:jira

Request

Path parameters

schemeId

integer

Required

Responses

Returned if the permission scheme is deleted.

DEL/rest/api/2/permissionscheme/{schemeId}
1 2 3 4 5 6 7 8 9 10 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().requestJira(route`/rest/api/2/permissionscheme/{schemeId}`, { method: 'DELETE' }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.text());
GET

Get permission scheme grants

Returns all permission grants for a permission scheme.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work
Granular:read:application-role:jira, read:field:jira, read:group:jira, read:permission:jira, read:project-role:jira ...(Show more)

Request

Path parameters

schemeId

integer

Required

Query parameters

expand

string

Responses

Returned if the request is successful.

application/json

PermissionGrants

List of permission grants.

GET/rest/api/2/permissionscheme/{schemeId}/permission
1 2 3 4 5 6 7 8 9 10 11 12 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().requestJira(route`/rest/api/2/permissionscheme/{schemeId}/permission`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { "expand": "user,group,projectRole,field,all", "permissions": [ { "holder": { "expand": "group", "parameter": "jira-core-users", "type": "group", "value": "ca85fac0-d974-40ca-a615-7af99c48d24f" }, "id": 10000, "permission": "ADMINISTER_PROJECTS", "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/permission/10000" } ] }
POST

Create permission grant

Creates a permission grant in a permission scheme.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredADMIN

ClassicRECOMMENDED:manage:jira-configuration
Granular:read:application-role:jira, read:field:jira, read:group:jira, read:permission:jira, read:project-role:jira ...(Show more)

Request

Path parameters

schemeId

integer

Required

Query parameters

expand

string

Request bodyapplication/json

The permission grant to create.

holder

PermissionHolder

permission

string

Additional Properties

any

Responses

Returned if the scheme permission is created.

application/json

PermissionGrant

Details about a permission granted to a user or group.

POST/rest/api/2/permissionscheme/{schemeId}/permission
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; var bodyData = `{ "holder": { "parameter": "jira-core-users", "type": "group", "value": "ca85fac0-d974-40ca-a615-7af99c48d24f" }, "permission": "ADMINISTER_PROJECTS" }`; const response = await api.asUser().requestJira(route`/rest/api/2/permissionscheme/{schemeId}/permission`, { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: bodyData }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
201Response
1 2 3 4 5 6 7 8 9 10 11 { "holder": { "expand": "group", "parameter": "jira-core-users", "type": "group", "value": "ca85fac0-d974-40ca-a615-7af99c48d24f" }, "id": 10000, "permission": "ADMINISTER_PROJECTS", "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/permission/10000" }
GET

Get permission scheme grant

Returns a permission grant.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work
Granular:read:application-role:jira, read:field:jira, read:group:jira, read:permission:jira, read:project-role:jira ...(Show more)

Request

Path parameters

schemeId

integer

Required
permissionId

integer

Required

Query parameters

expand

string

Responses

Returned if the request is successful.

application/json

PermissionGrant

Details about a permission granted to a user or group.

GET/rest/api/2/permissionscheme/{schemeId}/permission/{permissionId}
1 2 3 4 5 6 7 8 9 10 11 12 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().requestJira(route`/rest/api/2/permissionscheme/{schemeId}/permission/{permissionId}`, { headers: { 'Accept': 'application/json' } }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.json());
200Response
1 2 3 4 5 6 7 8 9 10 11 { "holder": { "expand": "group", "parameter": "jira-core-users", "type": "group", "value": "ca85fac0-d974-40ca-a615-7af99c48d24f" }, "id": 10000, "permission": "ADMINISTER_PROJECTS", "self": "https://your-domain.atlassian.net/rest/api/2/permissionscheme/permission/10000" }
DEL

Delete permission scheme grant

Deletes a permission grant from a permission scheme. See About permission schemes and grants for more details.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredADMIN

ClassicRECOMMENDED:manage:jira-configuration
Granular:delete:permission:jira

Request

Path parameters

schemeId

integer

Required
permissionId

integer

Required

Responses

Returned if the permission grant is deleted.

DEL/rest/api/2/permissionscheme/{schemeId}/permission/{permissionId}
1 2 3 4 5 6 7 8 9 10 // This sample uses Atlassian Forge // https://developer.atlassian.com/platform/forge/ import api, { route } from "@forge/api"; const response = await api.asUser().requestJira(route`/rest/api/2/permissionscheme/{schemeId}/permission/{permissionId}`, { method: 'DELETE' }); console.log(`Response: ${response.status} ${response.statusText}`); console.log(await response.text());

Rate this page: