About

The user management for Atlassian Cloud is a RESTful API that allows you to administer your organization’s managed accounts. You can update the details of managed account details such as their email address. You can also change the status of accounts, for example, deactivating and activating them. For more details on administering the managed accounts for your organization, see Administer managed accounts.

Getting started with the user management API

Before you start using the API, familiarize yourself with how the operations will affect the managed accounts in your organization.

To use the user management API, you must have a valid admin API key. The API key protects the API and ensures that you have the permission to manage the accounts.

Authentication

Obtaining an API key

To get the API key, navigate to your organization at admin.atlassian.com. If you have a valid Atlassian Access subscription, you’ll see the API keys under the Developers section. Choose API keys and click create API key. Choose a API key name that will allow you to remember the key.

An API key will be generated and displayed on screen. Remember to immediately store this key securely as it will not be visible again on the page. You’ll only have the ability to revoke existing API keys from the page.

Using the API key

Once you have generated your API key, you can use it as a bearer token to make requests to the API with the client of your choice.

Users

Retrieve a set of rights and limitations of the current user to manage the target Atlassian account

GET /users/{account_id}/manage

Request

Path parameters
account_id Required

string

The unique identifier of the user to retrieve

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

Array<string>

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

The consumer has permission to manage at least some aspect of the target user. Restrictions around the privileges specified are returned.

  • profile: 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
  • lifecycle.enablement: enable and disable the user's account
Content typeValue
application/json

object

Retrieve an Atlassian account

GET /users/{account_id}/manage/profile

Request

Path parameters
account_id Required

string

The unique identifier of the user to retrieve

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

The consumer has permission to manage the target user. The target user is returned.

Content typeValue
application/json

object

Update the target Atlassian account profile. Mutability per field is described by the 'profile' privilege.

PATCH /users/{account_id}/manage/profile

Request

Path parameters
account_id Required

string

The unique identifier 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": "Veronica Mars",
  "nickname": "marshmallow",
  "zoneinfo": "America/Los_Angeles",
  "locale": "en-US",
  "extended_profile": {
    "job_title": "Lead Investigator",
    "organization": "Mars Investigations",
    "department": "Investigations",
    "location": "Neptune, CA"
  }
}'

Responses

The consumer has permission to manage the target user. The target user is patched with the details given in the request, and the updated user is returned.

Content typeValue
application/json

object

Set the email address of the current user to the specified value. In order to perform this kind of change, the consumer _must_ be able to assert control of both the source and target domains as the updated email **will be considered verified**. The capacity to make use of this resource is exposed by the 'email.set' privilege. Note that this will also invalidate all active sessions.

PUT /users/{account_id}/manage/email

Request

Path parameters
account_id Required

string

The unique identifier of the user to change the email address for.

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.

Disable the user. The capacity to make use of this resource is exposed by the 'lifecycle.enablement' privilege. 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.

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

Request

Path parameters
account_id Required

string

The unique identifier of the user to disable.

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 the user. The capacity to make use of this resource is exposed by the 'lifecycle.enablement' privilege.

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

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.