Cloud

Jira Cloud platform / Reference / REST API v3

Users

This resource represent users. Use it to:

get, get a list of, create, and delete users.
get, set, and reset a user's default issue table columns.
get a list of the groups the user belongs to.
get a list of user account IDs for a list of usernames or user keys.

Operations

GET/rest/api/3/user POST/rest/api/3/user DEL/rest/api/3/user GET/rest/api/3/user/bulk GET/rest/api/3/user/bulk/migration GET/rest/api/3/user/columns PUT/rest/api/3/user/columns DEL/rest/api/3/user/columns GET/rest/api/3/user/email GET/rest/api/3/user/email/bulk GET/rest/api/3/user/groups GET/rest/api/3/users GET/rest/api/3/users/search

GET

Get user

Returns a user.

Privacy controls are applied to the response based on the user's preferences. This could mean, for example, that the user's email address is hidden. See the Profile visibility overview for more details.

Permissions required: Browse users and groups global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:application-role:jira, read:group:jira, read:user:jira, read:avatar:jira

Connect app scope required: READ

Request

Query parameters

accountId

string

username

string

key

string

expand

string

Responses

Returned if the request is successful.

application/json

User

A user with details as permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions:

User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, displayName provides an indication and other parameters have default values or are blank (for example, email is blank).
User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, accountId returns unknown and all other parameters have fallback values.
User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values.

GET/rest/api/3/user

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/user?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

{
  "accountId": "5b10a2844c20165700ede21g",
  "accountType": "atlassian",
  "active": true,
  "applicationRoles": {
    "items": [],
    "size": 1
  },
  "avatarUrls": {
    "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
    "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
    "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
    "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
  },
  "displayName": "Mia Krystof",
  "emailAddress": "mia@example.com",
  "groups": {
    "items": [],
    "size": 3
  },
  "key": "",
  "name": "",
  "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
  "timeZone": "Australia/Sydney"
}

POST

Create userExperimental

Creates a user. This resource is retained for legacy compatibility. As soon as a more suitable alternative is available this resource will be deprecated.

If the user exists and has access to Jira, the operation returns a 201 status. If the user exists but does not have access to Jira, the operation returns a 400 status.

Permissions required: Administer Jira global permission.

Data Security Policy: Exempt from app access rules

Scopes

Connect apps cannot access this REST resource.

Request

Request bodyapplication/json

Details about the user to be created.

applicationKeys

array<string>

displayName

string

emailAddress

string

Required

key

string

name

string

password

string

products

array<string>

Required

Additional Properties

any

Responses

Returned if the request is successful.

application/json

User

A user with details as permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions:

User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, displayName provides an indication and other parameters have default values or are blank (for example, email is blank).
User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, accountId returns unknown and all other parameters have fallback values.
User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values.

POST/rest/api/3/user

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
//
// This API resource doesn't support Oauth2 (3LO). See alternate authorization methods:
// https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication
import api, { route } from "@forge/api";

var bodyData = `{
  "emailAddress": "mia@atlassian.com"
}`;

const response = await api.requestJira(route`/rest/api/3/user`, {
  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

{
  "accountId": "5b10a2844c20165700ede21g",
  "accountType": "atlassian",
  "active": true,
  "applicationRoles": {
    "items": [],
    "size": 1
  },
  "avatarUrls": {
    "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
    "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
    "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
    "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
  },
  "displayName": "Mia Krystof",
  "emailAddress": "mia@example.com",
  "groups": {
    "items": [],
    "size": 3
  },
  "key": "",
  "name": "",
  "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
  "timeZone": "Australia/Sydney"
}

DEL

Delete userExperimental

Deletes a user. If the operation completes successfully then the user is removed from Jira's user base. This operation does not delete the user's Atlassian account.

Permissions required: Site administration (that is, membership of the site-admin group).

Data Security Policy: Exempt from app access rules

Scopes

Connect apps cannot access this REST resource.

Request

Query parameters

accountId

string

Required

username

string

key

string

Responses

Returned if the request is successful.

DEL/rest/api/3/user

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
//
// This API resource doesn't support Oauth2 (3LO). See alternate authorization methods:
// https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication
import api, { route } from "@forge/api";

const response = await api.requestJira(route`/rest/api/3/user?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  method: 'DELETE'
});

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

GET

Bulk get usersExperimental

Returns a paginated list of the users specified by one or more account IDs.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:application-role:jira, read:group:jira, read:user:jira, read:avatar:jira

Connect app scope required: READ

Request

Query parameters

startAt

integer

maxResults

integer

username

array<string>

key

array<string>

accountId

array<string>

Required

Responses

Returned if the request is successful.

application/json

PageBeanUser

A page of items.

GET/rest/api/3/user/bulk

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/user/bulk?accountId={accountId}`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

{
  "isLast": true,
  "maxResults": 100,
  "startAt": 0,
  "total": 1,
  "values": [
    {
      "accountId": "5b10a2844c20165700ede21g",
      "accountType": "atlassian",
      "active": true,
      "avatarUrls": {
        "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
        "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
        "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
        "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
      },
      "displayName": "Mia Krystof",
      "emailAddress": "mia@example.com",
      "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
      "timeZone": "Australia/Sydney"
    }
  ]
}

GET

Get account IDs for usersExperimental

Returns the account IDs for the users specified in the key or username parameters. Note that multiple key or username parameters can be specified.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:user:jira

Connect app scope required: READ

Request

Query parameters

startAt

integer

maxResults

integer

username

array<string>

key

array<string>

Responses

Returned if the request is successful.

application/json

array<UserMigrationBean>

GET/rest/api/3/user/bulk/migration

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

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

200Response

[
  {
    "username": "mia",
    "accountId": "5b10a2844c20165700ede21g"
  },
  {
    "username": "emma",
    "accountId": "5b10ac8d82e05b22cc7d4ef5"
  }
]

GET

Get user default columns

Returns the default issue table columns for the user. If accountId is not passed in the request, the calling user's details are returned.

Permissions required:

Administer Jira global permission, to get the column details for any user.
Permission to access Jira, to get the calling user's column details.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:user.columns:jira, read:filter.column:jira

Connect app scope required: READ

Request

Query parameters

accountId

string

username

string

Responses

Returned if the request is successful.

application/json

array<ColumnItem>

GET/rest/api/3/user/columns

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/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

[
  {
    "label": "<string>",
    "value": "<string>"
  }
]

PUT

Set user default columns

Sets the default issue table columns for the user. If an account ID is not passed, the calling user's default columns are set. If no column details are sent, then all default columns are removed.

The parameters for this resource are expressed as HTML form data. For example, in curl:

curl -X PUT -d columns=summary -d columns=description https://your-domain.atlassian.net/rest/api/3/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5'

Permissions required:

Administer Jira global permission, to set the columns on any user.
Permission to access Jira, to set the calling user's columns.

Data Security Policy: Exempt from app access rules

Scopes

Connect apps cannot access this REST resource.

Request

Query parameters

accountId

string

Request body/ multipart/form-data

The ID of a column to set. To set multiple columns, send multiple columns parameters.

columns

array<string>

Responses

Returned if the request is successful.

application/json

any

PUT/rest/api/3/user/columns

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
//
// This API resource doesn't support Oauth2 (3LO). See alternate authorization methods:
// https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication
import api, { route } from "@forge/api";

const response = await api.requestJira(route`/rest/api/3/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json'
  }
});

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

DEL

Reset user default columns

Resets the default issue table columns for the user to the system default. If accountId is not passed, the calling user's default columns are reset.

Permissions required:

Administer Jira global permission, to set the columns on any user.
Permission to access Jira, to set the calling user's columns.

Data Security Policy: Exempt from app access rules

Scopes

Connect apps cannot access this REST resource.

Request

Query parameters

accountId

string

username

string

Responses

Returned if the request is successful.

DEL/rest/api/3/user/columns

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
//
// This API resource doesn't support Oauth2 (3LO). See alternate authorization methods:
// https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication
import api, { route } from "@forge/api";

const response = await api.requestJira(route`/rest/api/3/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  method: 'DELETE'
});

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

GET

Get user email

Returns a user's email address regardless of the user's profile visibility settings. For Connect apps, this API is only available to apps approved by Atlassian, according to these guidelines. For Forge apps, this API only supports access via asApp() requests.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

read:email-address:jira

Connect app scope required: ACCESS_EMAIL_ADDRESSES

Request

Query parameters

accountId

string

Required

Responses

Returned if the request is successful.

application/json

UnrestrictedUserEmail

GET/rest/api/3/user/email

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
//
// This API resource doesn't support Oauth2 (3LO). See alternate authorization methods:
// https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication
import api, { route } from "@forge/api";

const response = await api.requestJira(route`/rest/api/3/user/email?accountId={accountId}`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

{
  "accountId": "<string>",
  "email": "<string>"
}

GET

Get user email bulk

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

read:email-address:jira

Connect app scope required: ACCESS_EMAIL_ADDRESSES

Request

Query parameters

accountId

array<string>

Required

Responses

Returned if the request is successful.

application/json

UnrestrictedUserEmail

GET/rest/api/3/user/email/bulk

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
//
// This API resource doesn't support Oauth2 (3LO). See alternate authorization methods:
// https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication
import api, { route } from "@forge/api";

const response = await api.requestJira(route`/rest/api/3/user/email/bulk?accountId={accountId}`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

{
  "accountId": "<string>",
  "email": "<string>"
}

GET

Get user groups

Returns the groups to which a user belongs.

Permissions required: Browse users and groups global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:group:jira

Connect app scope required: READ

Request

Query parameters

accountId

string

Required

username

string

key

string

Responses

Returned if the request is successful.

application/json

array<GroupName>

GET/rest/api/3/user/groups

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/user/groups?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

{
  "groupId": "276f955c-63d7-42c8-9520-92d01dca0625",
  "name": "jira-administrators",
  "self": "https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"
}

GET

Get all users default

Returns a list of all users, including active users, inactive users and previously deleted users that have an Atlassian account.

Privacy controls are applied to the response based on the users' preferences. This could mean, for example, that the user's email address is hidden. See the Profile visibility overview for more details.

Permissions required: Browse users and groups global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:user:jira, read:application-role:jira, read:avatar:jira, read:group:jira

Connect apps cannot access this REST resource.

Request

Query parameters

startAt

integer

maxResults

integer

Responses

Returned if the request is successful.

application/json

array<User>

GET/rest/api/3/users

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

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

200Response

[
  {
    "accountId": "5b10a2844c20165700ede21g",
    "accountType": "atlassian",
    "active": false,
    "avatarUrls": {
      "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
      "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
      "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
      "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
    },
    "displayName": "Mia Krystof",
    "key": "",
    "name": "",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
  },
  {
    "accountId": "5b10ac8d82e05b22cc7d4ef5",
    "accountType": "atlassian",
    "active": false,
    "avatarUrls": {
      "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=16&s=16",
      "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=24&s=24",
      "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=32&s=32",
      "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=48&s=48"
    },
    "displayName": "Emma Richards",
    "key": "",
    "name": "",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10ac8d82e05b22cc7d4ef5"
  }
]

GET

Get all users

Returns a list of all users, including active users, inactive users and previously deleted users that have an Atlassian account.

Permissions required: Browse users and groups global permission.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:user:jira, read:application-role:jira, read:avatar:jira, read:group:jira

Connect apps cannot access this REST resource.

Request

Query parameters

startAt

integer

maxResults

integer

Responses

Returned if the request is successful.

application/json

array<User>

GET/rest/api/3/users/search

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

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

200Response

[
  {
    "accountId": "5b10a2844c20165700ede21g",
    "accountType": "atlassian",
    "active": false,
    "avatarUrls": {
      "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
      "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
      "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
      "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
    },
    "displayName": "Mia Krystof",
    "key": "",
    "name": "",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
  },
  {
    "accountId": "5b10ac8d82e05b22cc7d4ef5",
    "accountType": "atlassian",
    "active": false,
    "avatarUrls": {
      "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=16&s=16",
      "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=24&s=24",
      "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=32&s=32",
      "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=48&s=48"
    },
    "displayName": "Emma Richards",
    "key": "",
    "name": "",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10ac8d82e05b22cc7d4ef5"
  }
]