Cloud

Jira Cloud platform / Reference / REST API v2

Project role actors

This resource represents the users assigned to project roles. Use it to get, add, and remove default users from project roles. Also use it to add and remove users from a project role associated with a project.

Operations

PUT/rest/api/2/project/{projectIdOrKey}/role/{id}POST/rest/api/2/project/{projectIdOrKey}/role/{id}DEL/rest/api/2/project/{projectIdOrKey}/role/{id}GET/rest/api/2/role/{id}/actors POST/rest/api/2/role/{id}/actors DEL/rest/api/2/role/{id}/actors

PUT

Set actors for project role

Sets the actors for a project role for a project, replacing all existing actors.

To add actors to the project without overwriting the existing list, use Add actors to project role.

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

Data Security Policy: Exempt from app access rules

Scopes

Connect app scope required: PROJECT_ADMIN

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-project

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

Request

Path parameters

projectIdOrKey

string

Required

integer

Required

Request bodyapplication/json

The groups or users to associate with the project role for this project. Provide the user account ID, group name, or group ID. As a group's name can change, use of group ID is recommended.

categorisedActors

object

Responses

Returned if the request is successful. The complete list of actors for the project is returned.

application/json

ProjectRole

Details about the roles in a project.

PUT/rest/api/2/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";

var bodyData = `{
  "categorisedActors": {
    "atlassian-group-role-actor-id": [
      "952d12c3-5b5b-4d04-bb32-44d383afc4b2"
    ],
    "atlassian-user-role-actor": [
      "12345678-9abc-def1-2345-6789abcdef12"
    ]
  }
}`;

const response = await api.asUser().requestJira(route`/rest/api/2/project/{projectIdOrKey}/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/2/project/MKY/role/10360"
}

POST

Add actors to project role

Adds actors to a project role for the project.

To replace all actors for the project, use Set actors for project role.

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

Connect app scope required: PROJECT_ADMIN

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

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

Request

Path parameters

projectIdOrKey

string

Required

integer

Required

Request bodyapplication/json

The groups or users to associate with the project role for this project. Provide the user account ID, group name, or group ID. As a group's name can change, use of group ID is recommended.

group

array<string>

groupId

array<string>

user

array<string>

Responses

Returned if the request is successful. The complete list of actors for the project is returned.

For example, the cURL request above adds a group, jira-developers. For the response below to be returned as a result of that request, the user Mia Krystof would have previously been added as a user actor for this project.

application/json

ProjectRole

Details about the roles in a project.

POST/rest/api/2/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";

var bodyData = `{
  "groupId": [
    "952d12c3-5b5b-4d04-bb32-44d383afc4b2"
  ]
}`;

const response = await api.asUser().requestJira(route`/rest/api/2/project/{projectIdOrKey}/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/2/project/MKY/role/10360"
}

DEL

Delete actors from project role

Deletes actors from a project role for the project.

To remove default actors from the project role, use Delete default actors from project role.

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

Connect app scope required: PROJECT_ADMIN

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-project

Granular:delete:project-role:jira

Request

Path parameters

projectIdOrKey

string

Required

integer

Required

Query parameters

user

string

group

string

groupId

string

Responses

Returned if the request is successful.

DEL/rest/api/2/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/2/project/{projectIdOrKey}/role/{id}?user=5b10ac8d82e05b22cc7d4ef5`, {
  method: 'DELETE'
});

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

GET

Get default actors for project role

Returns the default actors for the project role.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

Connect app scope required: ADMIN

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)

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/2/role/{id}/actors

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

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

200Response

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

POST

Add default actors to project role

Adds default actors to a role. You may add groups or users, but you cannot add groups and users in the same request.

Changing a project role's default actors does not affect project role members for projects already created.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

Connect app scope required: ADMIN

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

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

Request

Path parameters

integer

Required

Request bodyapplication/json

group

array<string>

groupId

array<string>

user

array<string>

Responses

Returned if the request is successful.

application/json

ProjectRole

Details about the roles in a project.

POST/rest/api/2/role/{id}/actors

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 = `{
  "user": [
    "admin"
  ]
}`;

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

DEL

Delete default actors from project role

Deletes the default actors from a project role. You may delete a group or user, but you cannot delete a group and a user in the same request.

Changing a project role's default actors does not affect project role members for projects already created.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

Connect app scope required: ADMIN

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

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

Request

Path parameters

integer

Required

Query parameters

user

string

groupId

string

group

string

Responses

Returned if the request is successful.

application/json

ProjectRole

Details about the roles in a project.

DEL/rest/api/2/role/{id}/actors

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/2/role/{id}/actors?user=5b10ac8d82e05b22cc7d4ef5`, {
  method: 'DELETE',
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

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