Cloud

Jira Cloud platform / Reference / REST API v3

Project roles

This resource represents the roles that users can play in projects. Use this resource to get, create, update, and delete project roles.

Operations

GET/rest/api/3/project/{projectIdOrKey}/role GET/rest/api/3/project/{projectIdOrKey}/role/{id}GET/rest/api/3/project/{projectIdOrKey}/roledetails GET/rest/api/3/role POST/rest/api/3/role GET/rest/api/3/role/{id}PUT/rest/api/3/role/{id}POST/rest/api/3/role/{id}DEL/rest/api/3/role/{id}

GET

Get project roles for project

Returns a list of project roles for the project returning the name and self URL for each role.

Note that all project roles are shared with all projects in Jira Cloud. See Get all project roles for more information.

This operation can be accessed anonymously.

Permissions required: Administer Projects project permission for any project on the site or Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:project-role:jira

Connect app scope required: READ

Request

Path parameters

projectIdOrKey

string

Required

Responses

Returned if the request is successful.

application/json

object

GET/rest/api/3/project/{projectIdOrKey}/role

Forge

curl

Node.js

Java

Python

PHP

// 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/3/project/{projectIdOrKey}/role`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "Administrators": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10002",
  "Developers": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10000",
  "Users": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10001"
}

GET

Get project role for project

Returns a project role's details and actors associated with the project. The list of actors is sorted by display name.

To check whether a user belongs to a role based on their group memberships, use Get user with the groups expand parameter selected. Then check whether the user keys and groups match with the actors returned for the project.

This operation can be accessed anonymously.

Permissions required: Administer Projects project permission for the project or Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:user:jira, read:group:jira, read:project-role:jira, read:project:jira, read:avatar:jira ...(Show more)

Connect app scope required: READ

Request

Path parameters

projectIdOrKey

string

Required

integer

Required

Query parameters

excludeInactiveUsers

boolean

Responses

Returned if the request is successful.

application/json

ProjectRole

Details about the roles in a project.

GET/rest/api/3/project/{projectIdOrKey}/role/{id}

Forge

curl

Node.js

Java

Python

PHP

// 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/3/project/{projectIdOrKey}/role/{id}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "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"
}

GET

Get project role details

Returns all project roles and the details for each role. Note that the list of project roles is common to all projects.

This operation can be accessed anonymously.

Permissions required: Administer Jira global permission or Administer projects project permission for the project.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:project-category:jira, read:project-role:jira, read:project:jira, read:avatar:jira

Connect app scope required: READ

Request

Path parameters

projectIdOrKey

string

Required

Query parameters

currentMember

boolean

excludeConnectAddons

boolean

Responses

Returned if the request is successful.

application/json

array<ProjectRoleDetails>

GET/rest/api/3/project/{projectIdOrKey}/roledetails

Forge

curl

Node.js

Java

Python

PHP

// 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/3/project/{projectIdOrKey}/roledetails`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

[
  {
    "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360",
    "name": "Developers",
    "id": 10360,
    "description": "A project role that represents developers in a project",
    "admin": false,
    "default": true,
    "roleConfigurable": true,
    "translatedName": "Developers"
  }
]

GET

Get all project roles

Gets a list of all project roles, complete with project role details and default actors.

About project roles

Project roles are a flexible way to to associate users and groups with projects. In Jira Cloud, the list of project roles is shared globally with all projects, but each project can have a different set of actors associated with it (unlike groups, which have the same membership throughout all Jira applications).

Project roles are used in permission schemes, email notification schemes, issue security levels, comment visibility, and workflow conditions.

Members and actors

In the Jira REST API, a member of a project role is called an actor. An actor is a group or user associated with a project role.

Actors may be set as default members of the project role or set at the project level:

Default actors: Users and groups that are assigned to the project role for all newly created projects. The default actors can be removed at the project level later if desired.
Actors: Users and groups that are associated with a project role for a project, which may differ from the default actors. This enables you to assign a user to different roles in different projects.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:read:user:jira, read:group:jira, read:project-role:jira, read:project:jira, read:avatar:jira ...(Show more)

Connect app scope required: ADMIN

Request

This request has no parameters.

Responses

Returned if the request is successful.

application/json

array<ProjectRole>

GET/rest/api/3/role

Forge

curl

Node.js

Java

Python

PHP

// 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/3/role`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

[
  {
    "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"
  }
]

POST

Create project role

Creates a new project role with no default actors. You can use the Add default actors to project role operation to add default actors to the project role after creating it.

Note that although a new project role is available to all projects upon creation, any default actors that are associated with the project role are not added to projects that existed prior to the role being created.<

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:read:user:jira, read:group:jira, read:project:jira, write:project-role:jira, read:avatar:jira ...(Show more)

Connect app scope required: ADMIN

Request

Request bodyapplication/json

description

string

name

string

Responses

Returned if the request is successful.

application/json

ProjectRole

Details about the roles in a project.

POST/rest/api/3/role

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "description": "A project role that represents developers in a project",
  "name": "Developers"
}`;

const response = await api.asUser().requestJira(route`/rest/api/3/role`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "description": "A project role that represents developers in a project",
  "id": 10360,
  "name": "Developers",
  "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360"
}

GET

Get project role by ID

Gets the project role details and the default actors associated with the role. The list of default actors is sorted by display name.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:read:user:jira, read:group:jira, read:project-role:jira, read:project:jira, read:avatar:jira ...(Show more)

Connect app scope required: ADMIN

Request

Path parameters

integer

Required

Responses

Returned if the request is successful.

application/json

ProjectRole

Details about the roles in a project.

GET/rest/api/3/role/{id}

Forge

curl

Node.js

Java

Python

PHP

// 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/3/role/{id}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "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"
}

PUT

Fully update project role

Updates the project role's name and description. You must include both a name and a description in the request.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:read:user:jira, read:group:jira, read:project:jira, write:project-role:jira, read:avatar:jira ...(Show more)

Connect app scope required: ADMIN

Request

Path parameters

integer

Required

Request bodyapplication/json

description

string

name

string

Responses

Returned if the request is successful.

application/json

ProjectRole

Details about the roles in a project.

PUT/rest/api/3/role/{id}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "description": "A project role that represents developers in a project",
  "name": "Developers"
}`;

const response = await api.asUser().requestJira(route`/rest/api/3/role/{id}`, {
  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

{
  "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"
}

POST

Partial update project role

Updates either the project role's name or its description.

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.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:read:user:jira, read:group:jira, read:project:jira, write:project-role:jira, read:avatar:jira ...(Show more)

Connect app scope required: ADMIN

Request

Path parameters

integer

Required

Request bodyapplication/json

description

string

name

string

Responses

Returned if the request is successful.

application/json

ProjectRole

Details about the roles in a project.

POST/rest/api/3/role/{id}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "description": "A project role that represents developers in a project",
  "name": "Developers"
}`;

const response = await api.asUser().requestJira(route`/rest/api/3/role/{id}`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "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"
}

DEL

Delete project role

Deletes a project role. You must specify a replacement project role if you wish to delete a project role that is in use.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:delete:project-role:jira

Connect app scope required: ADMIN

Request

Path parameters

integer

Required

Query parameters

swap

integer

Responses

Returned if the request is successful.

DEL/rest/api/3/role/{id}

Forge

curl

Node.js

Java

Python

PHP

// 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/3/role/{id}`, {
  method: 'DELETE'
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());