Atlassian Jira Permission Scheme API
The Atlassian Jira Permission Scheme API enables creating and managing permission schemes for controlling access within Jira.
OpenAPI Specification
components:
schemas:
PermissionScheme:
additionalProperties: true
description: Details of a permission scheme.
properties:
description:
description: A description for the permission scheme.
type: string
expand:
description: The expand options available for the permission scheme.
readOnly: true
type: string
id:
description: The ID of the permission scheme.
format: int64
readOnly: true
type: integer
name:
description: The name of the permission scheme. Must be unique.
type: string
permissions:
description: >-
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.
items:
$ref: '#/components/schemas/PermissionGrant'
type: array
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: The scope of the permission scheme.
self:
description: The URL of the permission scheme.
format: uri
readOnly: true
type: string
required:
- name
type: object
PermissionGrants:
additionalProperties: false
description: List of permission grants.
properties:
expand:
description: >-
Expand options that include additional permission grant details in
the response.
readOnly: true
type: string
permissions:
description: Permission grants list.
items:
$ref: '#/components/schemas/PermissionGrant'
readOnly: true
type: array
type: object
PermissionGrant:
additionalProperties: true
description: Details about a permission granted to a user or group.
properties:
holder:
allOf:
- $ref: '#/components/schemas/PermissionHolder'
description: >-
The user or group being granted the permission. It consists of a
`type`, a type-dependent `parameter` and a type-dependent `value`.
See [Holder object](../api-group-permission-schemes/#holder-object)
in *Get all permission schemes* for more information.
id:
description: The ID of the permission granted details.
format: int64
readOnly: true
type: integer
permission:
description: >-
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.
type: string
self:
description: The URL of the permission granted details.
format: uri
readOnly: true
type: string
type: object
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: [email protected]
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/permissionscheme/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/permissionscheme/{schemeId}:
delete:
deprecated: false
description: >-
Deletes a permission scheme.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianDeletepermissionscheme
parameters:
- description: The ID of the permission scheme being deleted.
in: path
name: schemeId
required: true
schema:
format: int64
type: integer
responses:
'204':
description: Returned if the permission scheme is deleted.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the permission scheme is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Delete Permission Scheme
tags:
- Permission Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- delete:permission-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
get:
deprecated: false
description: >-
Returns a permission scheme.<br><br>**[Permissions](#permissions)
required:** Permission to access Jira.
operationId: atlassianGetpermissionscheme
parameters:
- description: The ID of the permission scheme to return.
in: path
name: schemeId
required: true
schema:
format: int64
type: integer
- description: >-
Use expand to include additional information in the response. This
parameter accepts a comma-separated list. Note that permissions are
included when you specify any value. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about the custom field granted the permission.
* `group` Returns information about the group that is granted the permission.
* `permissions` Returns all permission grants for each permission scheme.
* `projectRole` Returns information about the project role granted the permission.
* `user` Returns information about the user who is granted the permission.
in: query
name: expand
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"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/3/permissionscheme/permission/10000"}],"self":"https://your-domain.atlassian.net/rest/api/3/permissionscheme/10000"}
schema:
$ref: '#/components/schemas/PermissionScheme'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the permission scheme is not found or the user does not
have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
summary: Atlassian Get Permission Scheme
tags:
- Permission Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:application-role:jira
- read:field:jira
- read:group:jira
- read:permission-scheme:jira
- read:permission:jira
- read:project-role:jira
- read:user:jira
- read:avatar:jira
- read:project-category:jira
- read:project:jira
state: Beta
x-atlassian-connect-scope: READ
put:
deprecated: false
description: >-
Updates a permission scheme. Below are some important things to note
when using this resource:<br><br> * If a permissions list is present in
the request, then it is set in the permission scheme, overwriting *all
existing* grants.<br> * If you want to update only the name and
description, then do not send a permissions list in the request.<br> * Sending an empty list will remove all permission grants from the
permission scheme.<br><br>If you want to add or delete a permission
grant instead of updating the whole list, see [Create permission
grant](#api-rest-api-3-permissionscheme-schemeId-permission-post) or
[Delete permission scheme
entity](#api-rest-api-3-permissionscheme-schemeId-permission-permissionId-delete).<br><br>See
[About permission schemes and
grants](../api-group-permission-schemes/#about-permission-schemes-and-grants)
for more details.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianUpdatepermissionscheme
parameters:
- description: The ID of the permission scheme to update.
in: path
name: schemeId
required: true
schema:
format: int64
type: integer
- description: >-
Use expand to include additional information in the response. This
parameter accepts a comma-separated list. Note that permissions are
always included when you specify any value. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about the custom field granted the permission.
* `group` Returns information about the group that is granted the permission.
* `permissions` Returns all permission grants for each permission scheme.
* `projectRole` Returns information about the project role granted the permission.
* `user` Returns information about the user who is granted the permission.
in: query
name: expand
schema:
type: string
requestBody:
content:
application/json:
example:
description: description
name: Example permission scheme
permissions:
- holder:
parameter: jira-core-users
type: group
value: ca85fac0-d974-40ca-a615-7af99c48d24f
permission: ADMINISTER_PROJECTS
schema:
$ref: '#/components/schemas/PermissionScheme'
required: true
responses:
'200':
content:
application/json:
example: >-
{"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/3/permissionscheme/permission/10000"}],"self":"https://your-domain.atlassian.net/rest/api/3/permissionscheme/10000"}
schema:
$ref: '#/components/schemas/PermissionScheme'
description: Returned if the scheme is updated.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: |-
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':
description: Returned if the permission scheme is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Update Permission Scheme
tags:
- Permission Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- write:permission-scheme:jira
- read:application-role:jira
- read:field:jira
- read:group:jira
- read:permission-scheme:jira
- read:permission:jira
- read:project-role:jira
- read:user:jira
- read:avatar:jira
- read:project-category:jira
- read:project:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/permissionscheme/{schemeId}/permission:
get:
deprecated: false
description: >-
Returns all permission grants for a permission
scheme.<br><br>**[Permissions](#permissions) required:** Permission to
access Jira.
operationId: atlassianGetpermissionschemegrants
parameters:
- description: The ID of the permission scheme.
in: path
name: schemeId
required: true
schema:
format: int64
type: integer
- description: >-
Use expand to include additional information in the response. This
parameter accepts a comma-separated list. Note that permissions are
always included when you specify any value. Expand options include:
* `permissions` Returns all permission grants for each permission scheme.
* `user` Returns information about the user who is granted the permission.
* `group` Returns information about the group that is granted the permission.
* `projectRole` Returns information about the project role granted the permission.
* `field` Returns information about the custom field granted the permission.
* `all` Returns all expandable information.
in: query
name: expand
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"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/3/permissionscheme/permission/10000"}]}
schema:
$ref: '#/components/schemas/PermissionGrants'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the permission schemes is not found or the user does not
have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
summary: Atlassian Get Permission Scheme Grants
tags:
- Permission Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:application-role:jira
- read:field:jira
- read:group:jira
- read:permission:jira
- read:project-role:jira
- read:user:jira
state: Beta
x-atlassian-connect-scope: READ
post:
deprecated: false
description: >-
Creates a permission grant in a permission
scheme.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianCreatepermissiongrant
parameters:
- description: >-
The ID of the permission scheme in which to create a new permission
grant.
in: path
name: schemeId
required: true
schema:
format: int64
type: integer
- description: >-
Use expand to include additional information in the response. This
parameter accepts a comma-separated list. Note that permissions are
always included when you specify any value. Expand options include:
* `permissions` Returns all permission grants for each permission scheme.
* `user` Returns information about the user who is granted the permission.
* `group` Returns information about the group that is granted the permission.
* `projectRole` Returns information about the project role granted the permission.
* `field` Returns information about the custom field granted the permission.
* `all` Returns all expandable information.
in: query
name: expand
schema:
type: string
requestBody:
content:
application/json:
example:
holder:
parameter: jira-core-users
type: group
value: ca85fac0-d974-40ca-a615-7af99c48d24f
permission: ADMINISTER_PROJECTS
schema:
$ref: '#/components/schemas/PermissionGrant'
description: The permission grant to create.
required: true
responses:
'201':
content:
application/json:
example: >-
{"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/3/permissionscheme/permission/10000"}
schema:
$ref: '#/components/schemas/PermissionGrant'
description: Returned if the scheme permission is created.
'400':
description: >-
Returned if the value for expand is invalid or the same permission
grant is present.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Create Permission Grant
tags:
- Permission Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:application-role:jira
- read:field:jira
- read:group:jira
- read:permission:jira
- read:project-role:jira
- read:user:jira
- write:permission:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/permissionscheme/{schemeId}/permission/{permissionId}:
delete:
deprecated: false
description: >-
Deletes a permission grant from a permission scheme. See [About
permission schemes and
grants](../api-group-permission-schemes/#about-permission-schemes-and-grants)
for more details.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianDeletepermissionschemeentity
parameters:
- description: The ID of the permission scheme to delete the permission grant from.
in: path
name: schemeId
required: true
schema:
format: int64
type: integer
- description: The ID of the permission grant to delete.
in: path
name: permissionId
required: true
schema:
format: int64
type: integer
responses:
'204':
description: Returned if the permission grant is deleted.
'400':
description: Returned if permission grant with the provided ID is not found.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Delete Permission Scheme Grant
tags:
- Permission Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- delete:permission:jira
state: Beta
x-atlassian-connect-scope: ADMIN
get:
deprecated: false
description: >-
Returns a permission grant.<br><br>**[Permissions](#permissions)
required:** Permission to access Jira.
operationId: atlassianGetpermissionschemegrant
parameters:
- description: The ID of the permission scheme.
in: path
name: schemeId
required: true
schema:
format: int64
type: integer
- description: The ID of the permission grant.
in: path
name: permissionId
required: true
schema:
format: int64
type: integer
- description: >-
Use expand to include additional information in the response. This
parameter accepts a comma-separated list. Note that permissions are
always included when you specify any value. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about the custom field granted the permission.
* `group` Returns information about the group that is granted the permission.
* `permissions` Returns all permission grants for each permission scheme.
* `projectRole` Returns information about the project role granted the permission.
* `user` Returns information about the user who is granted the permission.
in: query
name: expand
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"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/3/permissionscheme/permission/10000"}
schema:
$ref: '#/components/schemas/PermissionGrant'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the permission scheme or permission grant is not found
or the user does not have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
summary: Atlassian Get Permission Scheme Grant
tags:
- Permission Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:application-role:jira
- read:field:jira
- read:group:jira
- read:permission:jira
- read:project-role:jira
- read:user:jira
state: Beta
x-atlassian-connect-scope: READ
servers:
- url: https://your-domain.atlassian.net
tags:
- name: Permission Schemes
x-atlassian-narrative:
documents:
- anchor: about
body: >-
The Jira REST API enables you to interact with Jira programmatically.
Use this API to
[build
apps](https://developer.atlassian.com/cloud/jira/platform/integrating-with-jira-cloud/),
script interactions with
Jira, or develop any other type of integration. This page documents the
REST resources available in Jira Cloud, including
the HTTP response codes and example requests and responses.
title: About
- anchor: version
body: >
This documentation is for **version 3** of the Jira Cloud platform REST
API, which is the latest version
but is in **beta**. [Version
2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and
version 3 of the API offer the same collection of operations. However,
version 3 provides support for
the [Atlassian Document
Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
(ADF) in:
- `body` in comments, including where comments are used in issue, issue
link, and transition resources.
- `comment` in worklogs.
- `description` and `environment` fields in issues.
- `textarea` type custom fields (multi-line text fields) in issues.
Single line custom fields
(`textfield`) accept a string and don't handle Atlassian Document Format content.
However, these new features are under development and may change.
title: Version
- anchor: authentication
body: >
### Forge apps
For Forge apps, [REST API
scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/)
are used when authenticating with Jira Cloud platform. See [Add scopes
to call an Atlassian REST
API](https://developer.atlassian.com/platform/forge/add-scopes-to-call-an-atlassian-rest-api/)
for more details.
The URIs for Forge app REST API calls have this structure:
`/rest/api/3/<resource-name>`
For example, `/rest/api/3/issue/DEMO-1`
### Connect apps
For Connect apps, authentication (JWT-based) is built into the Connect
libraries. Authorization is implemented using either
scopes (shown as _App scope required_ for operations on this page) or
user impersonation. See
[Security for Connect
apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)
for details.
The URIs for Connect app REST API calls have this structure:
`https://<site-url>/rest/api/3/<resource-name>`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
### Other integrations
For integrations that are not Forge or Connect apps, use OAuth 2.0
authorization code grants (3LO) for security
(3LO scopes are shown as for operations _OAuth scopes required_). See
[OAuth 2.0 (3LO)
apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
for details.
The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:
`https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/<resource-name>`
For example,
`https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/3/issue/DEMO-1`
### Ad-hoc API calls
For personal scripts, bots, and ad-hoc execution of the REST APIs use
basic authentication. See [Basic auth for REST
APIs](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/)
for details.
The URIs for basic authentication REST API calls have this structure:
`https://<site-url>/rest/api/3/<resource-name>`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
title: Authentication and authorization
- anchor: permissions
body: >
### Operation permissions
Most operations in this API require permissions. The calling user must
have the required permissions for an operation to
use it. Note that for Connect apps, the app user must have the required
permissions for the operation and the app must
have scopes that permit the operation.
A permission can be granted to a group, project role, or issue role that
the user is a member of, or granted directly to a user.
See [Permissions overview](https://confluence.atlassian.com/x/FQiiLQ)
for details. The most common permissions are:
- **Administer the Cloud site**: Users in the _site-admins_ group have
this
permission. See [Manage
groups](https://confluence.atlassian.com/x/24xjL) for details.
- **Administer Jira**: Granted by the _Jira Administrators_ global
permission. There is a default group for this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
- **Administer a project in Jira**: Granted by the _Administer projects_
project permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access a project in Jira**: Granted by the _Browse projects_ project
permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access Jira**: Granted by the _Jira Users_ global permission. Users
in the default product access group (for example,
_jira-software-users-acmesite_) have this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
### Anonymous access
Some operations provide support for anonymous access. However, anonymous
access is only available if
the Jira permission needed to access the object or records returned by
the operation is granted to
the _Public_ group. See [Allowing anonymous access to your
project](https://confluence.atlassian.com/x/GDxxLg)
for details.
If an operation is called anonymously and anonymous access is not
available, the operation will return
an error. Note that not all operations that correspond to objects that
can be given public access
provide for anonymous access.
title: Permissions
- anchor: expansion
body: >+
### Expansion
The Jira REST API uses resource expansion, which means that some parts
of a resource are not returned unless specified
in the request. This simplifies responses and minimizes network traffic.
To expand part of a resource in a request, use the expand query
parameter and specify the object(s) to be expanded.
If you need to expand nested objects, use the `.` dot notation. If you
need to expand multiple objects, use a
comma-separated list.
For example, the following request expands the `names` and
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-permissionscheme--openapi-original.yml