Atlassian Jira User API
The Atlassian Jira User API enables managing user accounts, properties, and permissions within Jira.
OpenAPI Specification
components:
schemas:
PageBeanUser:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/User'
readOnly: true
type: array
type: object
UnrestrictedUserEmail:
additionalProperties: true
properties:
accountId:
description: The accountId of the user
type: string
email:
description: The email of the user
type: string
type: object
FoundUsers:
additionalProperties: false
description: >-
The list of users found in a search, including header text (Showing X of
Y matching users) and total of matched users.
properties:
header:
description: >-
Header text indicating the number of users in the response and the
total number of users found in the search.
type: string
total:
description: The total number of users found in the search.
format: int32
type: integer
users:
items:
$ref: '#/components/schemas/UserPickerUser'
type: array
type: object
PropertyKeys:
additionalProperties: false
description: List of property keys.
properties:
keys:
description: Property key details.
items:
$ref: '#/components/schemas/PropertyKey'
readOnly: true
type: array
type: object
EntityProperty:
additionalProperties: false
description: >-
An entity property, for more information see [Entity
properties](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
properties:
key:
description: The key of the property. Required on create and update.
type: string
value:
description: The value of the property. Required on create and update.
type: object
PageBeanUserKey:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/UserKey'
readOnly: true
type: array
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/user/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/user/assignable/multiProjectSearch:
get:
deprecated: false
description: >-
Returns a list of users who can be assigned issues in one or more
projects. The list may be restricted to users whose attributes match a
string.<br><br>This operation takes the users in the range defined by
`startAt` and `maxResults`, up to the thousandth user, and then returns
only the users from that range that can be assigned issues in the
projects. This means the operation usually returns fewer users than
specified in `maxResults`. To get all the users who can be assigned
issues in the projects, use [Get all
users](#api-rest-api-3-users-search-get) and filter the records in your
code.<br><br>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](https://developer.atlassian.com/cloud/jira/platform/profile-visibility/)
for more details.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:** None.
operationId: atlassianFindbulkassignableusers
parameters:
- description: >-
A query string that is matched against user attributes, such as
`displayName` and `emailAddress`, to find relevant users. The string
can match the prefix of the attribute's value. For example,
*query=john* matches a user with a `displayName` of *John Smith* and
a user with an `emailAddress` of *[email protected]*. Required,
unless `accountId` is specified.
in: query
name: query
schema:
example: query
type: string
x-showInExample: 'true'
- description: >-
This parameter is no longer available. See the [deprecation
notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details.
in: query
name: username
schema:
type: string
- description: >-
A query string that is matched exactly against user `accountId`.
Required, unless `query` is specified.
in: query
name: accountId
schema:
maxLength: 128
type: string
- description: >-
A list of project keys (case sensitive). This parameter accepts a
comma-separated list.
in: query
name: projectKeys
required: true
schema:
type: string
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int32
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 50
format: int32
type: integer
responses:
'200':
content:
application/json:
example: >-
[{"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"}]
schema:
items:
$ref: '#/components/schemas/User'
type: array
description: Returned if the request is successful.
'400':
description: |-
Returned if:
* `projectKeys` is missing.
* `query` or `accountId` is missing.
* `query` and `accountId` are provided.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if one or more of the projects is not found.
'429':
description: >-
Returned if the rate limit is exceeded. User search endpoints share
a collective rate limit for the tenant, in addition to Jira's normal
rate limiting you may receive a rate limit for user search. Please
respect the Retry-After header.
security:
- basicAuth: []
- OAuth2:
- read:jira-user
- {}
summary: Atlassian Find Users Assignable To Projects
tags:
- User Search
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-user
state: Current
- scheme: OAuth2
scopes:
- read:project:jira
- read:user:jira
- read:application-role:jira
- read:avatar:jira
- read:group:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/user/assignable/search:
get:
deprecated: false
description: >-
Returns a list of users that can be assigned to an issue. Use this
operation to find the list of users who can be assigned to:<br><br> * a
new issue, by providing the `projectKeyOrId`.<br> * an updated issue,
by providing the `issueKey`.<br> * to an issue during a transition
(workflow action), by providing the `issueKey` and the transition id in
`actionDescriptorId`. You can obtain the IDs of an issue's valid
transitions using the `transitions` option in the `expand` parameter of
[ Get issue](#api-rest-api-3-issue-issueIdOrKey-get).<br><br>In all
these cases, you can pass an account ID to determine if a user can be
assigned to an issue. The user is returned in the response if they can
be assigned to the issue or issue transition.<br><br>This operation
takes the users in the range defined by `startAt` and `maxResults`, up
to the thousandth user, and then returns only the users from that range
that can be assigned the issue. This means the operation usually returns
fewer users than specified in `maxResults`. To get all the users who can
be assigned the issue, use [Get all
users](#api-rest-api-3-users-search-get) and filter the records in your
code.<br><br>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](https://developer.atlassian.com/cloud/jira/platform/profile-visibility/)
for more details.<br><br>**[Permissions](#permissions) required:**
*Browse users and groups* [global
permission](https://confluence.atlassian.com/x/x4dKLg) or *Assign
issues* [project permission](https://confluence.atlassian.com/x/yodKLg)
operationId: atlassianFindassignableusers
parameters:
- description: >-
A query string that is matched against user attributes, such as
`displayName`, and `emailAddress`, to find relevant users. The
string can match the prefix of the attribute's value. For example,
*query=john* matches a user with a `displayName` of *John Smith* and
a user with an `emailAddress` of *[email protected]*. Required,
unless `username` or `accountId` is specified.
in: query
name: query
schema:
example: query
type: string
x-showInExample: 'true'
- description: >-
The sessionId of this request. SessionId is the same until the
assignee is set.
in: query
name: sessionId
schema:
type: string
- description: >-
This parameter is no longer available. See the [deprecation
notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details.
in: query
name: username
schema:
type: string
- description: >-
A query string that is matched exactly against user `accountId`.
Required, unless `query` is specified.
in: query
name: accountId
schema:
maxLength: 128
type: string
- description: >-
The project ID or project key (case sensitive). Required, unless
`issueKey` is specified.
in: query
name: project
schema:
type: string
- description: The key of the issue. Required, unless `project` is specified.
in: query
name: issueKey
schema:
type: string
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int32
type: integer
- description: >-
The maximum number of items to return. This operation may return
less than the maximum number of items even if more are available.
The operation fetches users up to the maximum and then, from the
fetched users, returns only the users that can be assigned to the
issue.
in: query
name: maxResults
schema:
default: 50
format: int32
type: integer
- description: The ID of the transition.
in: query
name: actionDescriptorId
schema:
format: int32
type: integer
- in: query
name: recommend
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
example: >-
{"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":"[email protected]","groups":{"items":[],"size":3},"key":"","name":"","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","timeZone":"Australia/Sydney"}
schema:
items:
$ref: '#/components/schemas/User'
type: array
description: Returned if the request is successful.
'400':
description: |-
Returned if:
* `issueKey` or `project` is missing.
* `query` or `accountId` is missing.
* `query` and `accountId` are provided.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if the project, issue, or transition is not found.
'429':
description: >-
Returned if the rate limit is exceeded. User search endpoints share
a collective rate limit for the tenant, in addition to Jira's normal
rate limiting you may receive a rate limit for user search. Please
respect the Retry-After header.
security:
- basicAuth: []
- OAuth2:
- read:jira-user
- {}
summary: Atlassian Find Users Assignable To Issues
tags:
- User Search
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-user
state: Current
- scheme: OAuth2
scopes:
- read:issue:jira
- read:project:jira
- read:user:jira
- read:application-role:jira
- read:avatar:jira
- read:group:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/user/bulk:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of the users specified by one or
more account IDs.<br><br>**[Permissions](#permissions) required:**
Permission to access Jira.
operationId: atlassianBulkgetusers
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 10
format: int32
type: integer
- description: >-
This parameter is no longer available and will be removed from the
documentation soon. See the [deprecation
notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details.
in: query
name: username
schema:
items:
type: string
type: array
- description: >-
This parameter is no longer available and will be removed from the
documentation soon. See the [deprecation
notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details.
in: query
name: key
schema:
items:
type: string
type: array
- description: >-
The account ID of a user. To specify multiple users, pass multiple
`accountId` parameters. For example,
`accountId=5b10a2844c20165700ede21g&accountId=5b10ac8d82e05b22cc7d4ef5`.
in: query
name: accountId
required: true
schema:
example: 5b10ac8d82e05b22cc7d4ef5
items:
example: 5b10ac8d82e05b22cc7d4ef5
maxLength: 128
type: string
maxLength: 128
type: array
x-showInExample: 'true'
responses:
'200':
content:
application/json:
example: >-
{"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":"[email protected]","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","timeZone":"Australia/Sydney"}]}
schema:
$ref: '#/components/schemas/PageBeanUser'
description: Returned if the request is successful.
'400':
description: Returned if `accountID` is missing.
'401':
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- read:jira-user
summary: Atlassian Bulk Get Users
tags:
- Users
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-user
state: Current
- scheme: OAuth2
scopes:
- read:application-role:jira
- read:group:jira
- read:user:jira
- read:avatar:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/user/bulk/migration:
get:
deprecated: false
description: >-
Returns the account IDs for the users specified in the `key` or
`username` parameters. Note that multiple `key` or `username` parameters
can be specified.<br><br>**[Permissions](#permissions) required:**
Permission to access Jira.
operationId: atlassianBulkgetusersmigration
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 10
format: int32
type: integer
- description: >-
Username of a user. To specify multiple users, pass multiple copies
of this parameter. For example, `username=fred&username=barney`.
Required if `key` isn't provided. Cannot be provided if `key` is
present.
in: query
name: username
schema:
items:
type: string
type: array
- description: >-
Key of a user. To specify multiple users, pass multiple copies of
this parameter. For example, `key=fred&key=barney`. Required if
`username` isn't provided. Cannot be provided if `username` is
present.
in: query
name: key
schema:
items:
type: string
type: array
responses:
'200':
content:
application/json:
example: >-
[{"username":"mia","accountId":"5b10a2844c20165700ede21g"},{"username":"emma","accountId":"5b10ac8d82e05b22cc7d4ef5"}]
schema:
items:
$ref: '#/components/schemas/UserMigrationBean'
type: array
description: Returned if the request is successful.
'400':
description: Returned if `key` or `username`
'401':
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- read:jira-user
summary: Atlassian Get Account Ids For Users
tags:
- Users
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-user
state: Current
- scheme: OAuth2
scopes:
- read:user:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/user/columns:
delete:
deprecated: false
description: >-
Resets the default [ issue table
columns](https://confluence.atlassian.com/x/XYdKLg) for the user to the
system default. If `accountId` is not passed, the calling user's default
columns are reset.<br><br>**[Permissions](#permissions)
required:**<br><br> * *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg), to set the
columns on any user.<br> * Permission to access Jira, to set the
calling user's columns.
operationId: atlassianResetusercolumns
parameters:
- description: >-
The account ID of the user, which uniquely identifies the user
across all Atlassian products. For example,
*5b10ac8d82e05b22cc7d4ef5*.
in: query
name: accountId
schema:
example: 5b10ac8d82e05b22cc7d4ef5
maxLength: 128
type: string
x-showInExample: 'true'
- description: >-
This parameter is no longer available. See the [deprecation
notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details.
in: query
name: username
schema:
type: string
responses:
'204':
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 the necessary permission or is
not accessing their user record.
security:
- basicAuth: []
- {}
summary: Atlassian Reset User Default Columns
tags:
- Users
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: INACCESSIBLE
get:
deprecated: false
description: >-
Returns the default [issue table
columns](https://confluence.atlassian.com/x/XYdKLg) for the user. If
`accountId` is not passed in the request, the calling user's details are
returned.<br><br>**[Permissions](#permissions) required:**<br><br> * *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLgl), to get the
column details for any user.<br> * Permission to access Jira, to get
the calling user's column details.
operationId: atlassianGetuserdefaultcolumns
parameters:
- description: >-
The account ID of the user, which uniquely identifies the user
across all Atlassian products. For example,
*5b10ac8d82e05b22cc7d4ef5*.
in: query
name: accountId
schema:
example: 5b10ac8d82e05b22cc7d4ef5
maxLength: 128
type: string
x-showInExample: 'true'
- description: >-
This parameter is no longer available See the [deprecation
notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details.
in: query
name: username
schema:
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ColumnItem'
type: array
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 the necessary permission or is
not accessing their user record.
'404':
description: Returned if the requested user is not found.
security:
- basicAuth: []
- OAuth2:
- read:jira-user
- {}
summary: Atlassian Get User Default Columns
tags:
- Users
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-user
state: Current
- scheme: OAuth2
scopes:
- read:user.columns:jira
- read:filter.column:jira
state: Beta
x-atlassian-connect-scope: READ
put:
deprecated: false
description: >-
Sets the default [ issue table
columns](https://confluence.atlassian.com/x/XYdKLg) 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.<br><br>The parameters for this resource are expressed as HTML
form data. For example, in curl:<br><br>`curl -X PUT -d columns=summary
-d columns=description
https://your-domain.atlassian.net/rest/api/3/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5'`<br><br>**[Permissions](#permissions)
required:**<br><br> * *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg), to set the
columns on any user.<br> * Permission to access Jira, to set the
calling user's columns.
operationId: atlassianSetusercolumns
parameters:
- description: >-
The account ID of the user, which uniquely identifies the user
across all Atlassian products. For example,
*5b10ac8d82e05b22cc7d4ef5*.
in: query
name: accountId
schema:
example: 5b10ac8d82e05b22cc7d4ef5
maxLength: 128
type: string
x-showInExample: 'true'
requestBody:
content:
'*/*':
schema:
$ref: '#/components/schemas/UserColumnRequestBody'
multipart/form-data:
schema:
$ref: '#/components/schemas/UserColumnRequestBody'
description: >-
The ID of a column to set. To set multiple columns, send multiple
`columns` parameters.
required: true
responses:
'200':
content:
application/json:
schema: {}
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 the necessary permission or is
not accessing their user record.
'404':
description: Returned if the requested user is not found.
'429':
description: >-
Returned if the rate limit is exceeded. User search endpoints share
a collective rate limit for the tenant, in addition to Jira's normal
rate limiting you may receive a rate limit for user search. Please
respect the Retry-After header.
'500':
description: Returned if an invalid issue ta
# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-user--openapi-original.yml