About the user management REST API

Use this REST API to administer and edit the managed accounts in your organization by account ID. You can find the account ID for a user with get users in an organization.

Authentication and authorization

To use the user management REST API you must have a valid API key. The API key protects the API and ensures that you have permission to update and disable the accounts owned by your organization. You can use the same API key for the organizations REST API and the user management REST API. For more information, see Create an API key.

Once you have your API key, you can provide it as a bearer token in the Authorization part of your HTTPS header.

Version and URI

This documentation is for version 1 of the user management REST API. The URIs for resources have the following structure:

1
https://api.atlassian.com/admin/users/<resource-name>

Users

Get user management permissions

GET /users/{account_id}/manage

Returns the set of permissions you have for managing the specified Atlassian account

Request

Path parameters
account_id Required

string

The user account to manage

Pattern: [a-zA-Z0-9_|:-]{1,128}
Query parameters
privileges

Array<string>

Valid values: profile, profile.write, profile.read, email.set, email.initiateChange - lifecycle.enablement, linkedAccounts.read, apiToken.read, apiToken.delete, avatar, privacy.set

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/users/{account_id}/manage' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

You have permission to manage at least some aspect of the specified user account. Restrictions around the privileges specified are returned.

  • profile: DEPRECATED, replace by profile.write - profile.read: read the profile data of the user account - profile.write: refers to the object mutability of the user's profile (at PATCH ./profile)
  • email.set: set a new value for the user's email address - email.initiateChange: initiate an email address change - mfa.read: read the current MFA enrollment state for the user - mfa.unenroll: unenroll the user from MFA - password.set: set the user's password - password.reset: reset the user's password - lifecycle.enablement: enable and disable the user's account - apiToken.read: list the user's API tokens - apiToken.delete: delete API tokens from the account - apiToken.create: create API tokens for the account - avatar: set and delete the user's avatar - privacy.set: set visiblity of the user's personal information - linkedAccounts.read: list the external accounts (for auth) that are linked to this user account
Content typeValue
application/json

object

Get user profile

GET /users/{account_id}/manage/profile

Returns information about a single Atlassian account by ID

Request

Path parameters
account_id Required

string

The ID of the user

Pattern: [a-zA-Z0-9_|:-]{1,128}

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/users/{account_id}/manage/profile' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

You have permission to manage the user. The profile data is returned.

Content typeValue
application/json

object

Update a user profile

PATCH /users/{account_id}/manage/profile

Updates fields in a user account. The profile privilege details which fields you can change.

Request

Path parameters
account_id Required

string

The ID of the user to update

Pattern: [a-zA-Z0-9_|:-]{1,128}
Body parameters
Content typeValue
application/json

allOf [User, object]

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --request PATCH \
  --url 'https://api.atlassian.com/users/{account_id}/manage/profile' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Lila User",
  "nickname": "marshmallow",
  "zoneinfo": "America/Los_Angeles",
  "locale": "en-US",
  "extended_profile": {
    "job_title": "Lead Investigator",
    "organization": "Amalgamated Investigations",
    "department": "Investigations",
    "location": "Lompoc, CA"
  }
}'

Responses

You have permission to manage the user. The profile is updated.

Content typeValue
application/json

object

Set a user's email

PUT /users/{account_id}/manage/email

Sets the specified user's email address. Before using this endpoint, you must verify the target domain as the new email address will be considered verified. The permission to make use of this resource is exposed by the email.set privilege. This call invalidates all active sessions.

Request

Path parameters
account_id Required

string

The ID of the user

Pattern: [a-zA-Z0-9_|:-]{1,128}
Body parameters
email Required

string

The email address of the user.

Constraints

  • partMaxLength: The maximum length of the user part and of any subdomain is 255 characters.
  • validCharacters: Control and null characters are not allowed

Example

1
2
3
4
5
6
7
curl --request PUT \
  --url 'https://api.atlassian.com/users/{account_id}/manage/email' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "vmars@marsinvestigations.com"
}'

Responses

Everything went fine, nothing to return.

Get a user's API tokens

GET /users/{accountId}/manage/api-tokens

Gets the API tokens owned by the specified user.

Request

Path parameters
accountId Required

string

The ID of the user

Pattern: ^[a-zA-Z0-9_|:-]{1,128}$

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/users/{accountId}/manage/api-tokens' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Success

Content typeValue
application/json

Array<anything>

Delete an API token

DELETE /users/{accountId}/manage/api-tokens/{tokenId}

Deletes a specifid API token by ID.

Request

Path parameters
accountId Required

string

The ID of the user

Pattern: ^[a-zA-Z0-9_|:-]{1,128}$
tokenId Required

string

The ID of the API token

Example

1
2
3
curl --request DELETE \
  --url 'https://api.atlassian.com/users/{accountId}/manage/api-tokens/{tokenId}' \
  --header 'Authorization: Bearer <access_token>'

Responses

The API token was deleted

Disable a user

POST /users/{account_id}/manage/lifecycle/disable

Disables the specified user account. The permission to make use of this resource is exposed by the lifecycle.enablement privilege. You can optionally set a message associated with the block that will be shown to the user on attempted authentication. If none is supplied, a default message will be used.

Request

Path parameters
account_id Required

string

The ID of the user

Pattern: [a-zA-Z0-9_|:-]{1,128}
Body parameters
message

string

Example

1
2
3
4
5
6
7
curl --request POST \
  --url 'https://api.atlassian.com/users/{account_id}/manage/lifecycle/disable' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "message": "On 6-month suspension"
}'

Responses

Everything went fine, nothing to return.

Enable a user

POST /users/{account_id}/manage/lifecycle/enable

Enables the specified user account. The permission to make use of this resource is exposed by the lifecycle.enablement privilege. You can optionally set a message associated with the block that will be shown to the user on attempted authentication. If none is supplied, a default message will be used.

Request

Path parameters
account_id Required

string

The unique identifier of the user to enable.

Pattern: [a-zA-Z0-9_|:-]{1,128}

Example

1
2
3
curl --request POST \
  --url 'https://api.atlassian.com/users/{account_id}/manage/lifecycle/enable' \
  --header 'Authorization: Bearer <access_token>'

Responses

Everything went fine, nothing to return.