Atlassian Jira Role API
The Atlassian Jira Role API enables managing project roles and role actors within Jira.
OpenAPI Specification
components:
schemas:
ProjectRole:
additionalProperties: false
description: Details about the roles in a project.
properties:
actors:
description: The list of users who act in this role.
items:
$ref: '#/components/schemas/RoleActor'
readOnly: true
type: array
admin:
description: Whether this role is the admin role for the project.
readOnly: true
type: boolean
currentUserRole:
description: Whether the calling user is part of this role.
type: boolean
default:
description: Whether this role is the default role for the project
readOnly: true
type: boolean
description:
description: The description of the project role.
readOnly: true
type: string
id:
description: The ID of the project role.
format: int64
readOnly: true
type: integer
name:
description: The name of the project role.
type: string
roleConfigurable:
description: Whether the roles are configurable for this project.
readOnly: true
type: boolean
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: >-
The scope of the role. Indicated for roles associated with [next-gen
projects](https://confluence.atlassian.com/x/loMyO).
readOnly: true
self:
description: The URL the project role details.
format: uri
readOnly: true
type: string
translatedName:
description: The translated name of the project role.
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/role/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/role/{id}:
delete:
deprecated: false
description: >-
Deletes a project role. You must specify a replacement project role if
you wish to delete a project role that is in
use.<br><br>**[Permissions](#permissions) required:** *Administer Jira*
[global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianDeleteprojectrole
parameters:
- description: >-
The ID of the project role to delete. Use [Get all project
roles](#api-rest-api-3-role-get) to get a list of project role IDs.
in: path
name: id
required: true
schema:
format: int64
type: integer
- description: The ID of the project role that will replace the one being deleted.
in: query
name: swap
schema:
format: int64
type: integer
responses:
'204':
description: Returned if the request is successful.
'400':
description: >-
Returned if the request is invalid or if the replacement project
role is not found.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have administrative permissions.
'404':
description: Returned if the project role being deleted is not found.
'409':
description: >-
Returned if the project role being deleted is in use and a
replacement project role is not specified in the request.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Delete Project Role
tags:
- Project Roles
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:project-role:jira
state: Beta
x-atlassian-connect-scope: ADMIN
get:
deprecated: false
description: >-
Gets the project role details and the default actors associated with the
role. The list of default actors is sorted by display
name.<br><br>**[Permissions](#permissions) required:** *Administer Jira*
[global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetprojectrolebyid
parameters:
- description: >-
The ID of the project role. Use [Get all project
roles](#api-rest-api-3-role-get) to get a list of project role IDs.
in: path
name: id
required: true
schema:
format: int64
type: integer
responses:
'200':
content:
application/json:
example: >-
{"actors":[{"actorGroup":{"displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2","name":"jira-developers"},"displayName":"jira-developers","id":10240,"name":"jira-developers","type":"atlassian-group-role-actor","user":"jira-developers"},{"actorUser":{"accountId":"5b10a2844c20165700ede21g"},"displayName":"Mia
Krystof","id":10241,"type":"atlassian-user-role-actor"}],"description":"A
project role that represents developers in a
project","id":10360,"name":"Developers","scope":{"project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"},"type":"PROJECT"},"self":"https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"}
schema:
$ref: '#/components/schemas/ProjectRole'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have administrative permissions.
'404':
description: Returned if the project role is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Project Role By Id
tags:
- Project Roles
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:user:jira
- read:group:jira
- read:project-role:jira
- read:project:jira
- read:avatar:jira
- read:project-category:jira
state: Beta
x-atlassian-connect-scope: ADMIN
post:
deprecated: false
description: >-
Updates either the project role's name or its description.<br><br>You
cannot update both the name and description at the same time using this
operation. If you send a request with a name and a description only the
name is updated.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianPartialupdateprojectrole
parameters:
- description: >-
The ID of the project role. Use [Get all project
roles](#api-rest-api-3-role-get) to get a list of project role IDs.
in: path
name: id
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
description: A project role that represents developers in a project
name: Developers
schema:
$ref: '#/components/schemas/CreateUpdateRoleRequestBean'
required: true
responses:
'200':
content:
application/json:
example: >-
{"actors":[{"actorGroup":{"displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2","name":"jira-developers"},"displayName":"jira-developers","id":10240,"name":"jira-developers","type":"atlassian-group-role-actor","user":"jira-developers"},{"actorUser":{"accountId":"5b10a2844c20165700ede21g"},"displayName":"Mia
Krystof","id":10241,"type":"atlassian-user-role-actor"}],"description":"A
project role that represents developers in a
project","id":10360,"name":"Developers","scope":{"project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"},"type":"PROJECT"},"self":"https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"}
schema:
$ref: '#/components/schemas/ProjectRole'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have administrative permissions.
'404':
description: Returned if the project role is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Partial Update Project Role
tags:
- Project Roles
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:user:jira
- read:group:jira
- read:project:jira
- write:project-role:jira
- read:avatar:jira
- read:project-category:jira
- read:project-role:jira
state: Beta
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Updates the project role's name and description. You must include both a
name and a description in the
request.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianFullyupdateprojectrole
parameters:
- description: >-
The ID of the project role. Use [Get all project
roles](#api-rest-api-3-role-get) to get a list of project role IDs.
in: path
name: id
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
description: A project role that represents developers in a project
name: Developers
schema:
$ref: '#/components/schemas/CreateUpdateRoleRequestBean'
required: true
responses:
'200':
content:
application/json:
example: >-
{"actors":[{"actorGroup":{"displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2","name":"jira-developers"},"displayName":"jira-developers","id":10240,"name":"jira-developers","type":"atlassian-group-role-actor","user":"jira-developers"},{"actorUser":{"accountId":"5b10a2844c20165700ede21g"},"displayName":"Mia
Krystof","id":10241,"type":"atlassian-user-role-actor"}],"description":"A
project role that represents developers in a
project","id":10360,"name":"Developers","scope":{"project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"},"type":"PROJECT"},"self":"https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"}
schema:
$ref: '#/components/schemas/ProjectRole'
description: Returned if the request is successful.
'400':
description: >-
Returned if the request is not valid. The `name` cannot be empty or
start or end with whitespace.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have administrative permissions.
'404':
description: Returned if the project role is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Fully Update Project Role
tags:
- Project Roles
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:user:jira
- read:group:jira
- read:project:jira
- write:project-role:jira
- read:avatar:jira
- read:project-category:jira
- read:project-role:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/role/{id}/actors:
delete:
deprecated: false
description: >-
Deletes the [default actors](#api-rest-api-3-resolution-get) from a
project role. You may delete a group or user, but you cannot delete a
group and a user in the same request.<br><br>Changing a project role's
default actors does not affect project role members for projects already
created.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianDeleteprojectroleactorsfromrole
parameters:
- description: >-
The ID of the project role. Use [Get all project
roles](#api-rest-api-3-role-get) to get a list of project role IDs.
in: path
name: id
required: true
schema:
format: int64
type: integer
- description: The user account ID of the user to remove as a default actor.
in: query
name: user
schema:
example: 5b10ac8d82e05b22cc7d4ef5
type: string
x-showInExample: 'true'
- description: >-
The group ID of the group to be removed as a default actor. This
parameter cannot be used with the `group` parameter.
in: query
name: groupId
schema:
type: string
- description: >-
The group name of the group to be removed as a default actor.This
parameter cannot be used with the `groupId` parameter. As a group's
name can change, use of `groupId` is recommended.
in: query
name: group
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"actors":[{"actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"},"displayName":"jira-developers","id":10240,"name":"jira-developers","type":"atlassian-group-role-actor"}]}
schema:
$ref: '#/components/schemas/ProjectRole'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have administrative permissions.
'404':
description: Returned if the project role is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Delete Default Actors From Project Role
tags:
- Project Role Actors
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:project-role:jira
- read:user:jira
- read:group:jira
- read:project-role:jira
- read:project:jira
- read:avatar:jira
- read:project-category:jira
state: Beta
x-atlassian-connect-scope: ADMIN
get:
deprecated: false
description: >-
Returns the [default actors](#api-rest-api-3-resolution-get) for the
project role.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetprojectroleactorsforrole
parameters:
- description: >-
The ID of the project role. Use [Get all project
roles](#api-rest-api-3-role-get) to get a list of project role IDs.
in: path
name: id
required: true
schema:
format: int64
type: integer
responses:
'200':
content:
application/json:
example: >-
{"actors":[{"actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"},"displayName":"jira-developers","id":10240,"name":"jira-developers","type":"atlassian-group-role-actor"}]}
schema:
$ref: '#/components/schemas/ProjectRole'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have administrative permissions.
'404':
description: Returned if the project role is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Default Actors For Project Role
tags:
- Project Role Actors
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:user:jira
- read:group:jira
- read:project-role:jira
- read:project:jira
- read:avatar:jira
- read:project-category:jira
state: Beta
x-atlassian-connect-scope: ADMIN
post:
deprecated: false
description: >-
Adds [default actors](#api-rest-api-3-resolution-get) to a role. You may
add groups or users, but you cannot add groups and users in the same
request.<br><br>Changing a project role's default actors does not affect
project role members for projects already
created.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianAddprojectroleactorstorole
parameters:
- description: >-
The ID of the project role. Use [Get all project
roles](#api-rest-api-3-role-get) to get a list of project role IDs.
in: path
name: id
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
user:
- admin
schema:
$ref: '#/components/schemas/ActorInputBean'
required: true
responses:
'200':
content:
application/json:
example: >-
{"actors":[{"actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"},"displayName":"jira-developers","id":10240,"name":"jira-developers","type":"atlassian-group-role-actor"}]}
schema:
$ref: '#/components/schemas/ProjectRole'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have administrative permissions.
'404':
description: Returned if the project role is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Add Default Actors To Project Role
tags:
- Project Role Actors
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:user:jira
- read:group:jira
- read:project-role:jira
- read:project:jira
- write:project-role:jira
- read:avatar:jira
- read:project-category:jira
state: Beta
x-atlassian-connect-scope: ADMIN
servers:
- url: https://your-domain.atlassian.net
tags:
- name: Project Role Actors
- name: Project Roles
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
`renderedFields` properties for the _JRACLOUD-34423_ issue:
`GET issue/JRACLOUD-34423?expand=names,renderedFields`
To discover which object can be expanded, refer to the `expand` property
in the object.
In the JSON example below, the resource declares `widgets` as
expandable.
```json
{
"expand": "widgets",
"self": "https://your-domain.atlassian.net/rest/api/3/resource/KEY-1",
"widgets": {
"widgets": [],
"size": 5
}
}
```
### Pagination
The Jira REST API uses pagination to improve performance. Pagination is
enforced for operations that could return a large
collection of items. When you make a request to a paginated resource,
the response wraps the returned array of values in
a JSON object with paging metadata. For example:
```json
{
"startAt" : 0,
"maxResults" : 10,
"total": 200,
"isLast": false,
"values": [
{ /* result 0 */ },
{ /* result 1 */ },
{ /* result 2 */ }
]
}
```
* `startAt` is the index of the first item returned in the page.
* `maxResults` is the maximum number of items that a page can return.
Each operation can have a different limit for
the number of items returned, and these limits may change without notice. To find the maximum number of items
that an operation could return, set `maxResults` to a large number—for example, over 1000—and if the returned value of `maxResults` is less than the requested value, the returned value is the maximum.
* `total` is the total number of items contained in all pages. This
number **_may change_** as the client
requests the subsequent pages, therefore the client should always assume
that the requested page can be empty. Note
that this property is not returned for all operations.
* `isLast` indicates whether the page returned is the last one. Note
that this property is not returned for all operations.
### Ordering
Some operations support ordering the elements of a response by a field.
Check the documentation for the operation to
confirm whether ordering of a response is supported and which fields can
be used. Responses are listed in ascending order
by default. You can change the order using the `orderby` query parameter
with a `-` or `+` symbol. For example:
* `?orderBy=name` to order by `name` field ascending.
* `?orderBy=+name` to order by `name` field ascending.
* `?orderBy=-name` to order by `name` field descending.
title: Expansion, pagina
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-role--openapi-original.yml