• Users
  • Groups
  • Schemas
  • Service Provider Configuration
Cloud
User provisioning REST API / Reference / REST API

Rate this page:

Users

Postman Collection
OpenAPI

The following user attributes can be updated through the user provisioning API.

User profile fieldSCIM fieldAttribute typeRequired
Display namedisplayNameSingularfalse
Email addressemailsMulti-Valuedtrue
OrganizationorganizationSingularfalse
Job titletitleSingularfalse
TimezonetimezoneSingularfalse
DepartmentdepartmentSingularfalse
Preferred languagepreferredLanguageSingularfalse
GET

Get a user by ID

Retrieves a user from the directory based on their userId.

Request

Path parameters

directoryId

string

Required
userId

string

Required

Query parameters

attributes

string

excludedAttributes

string

Responses

User has been returned successfully.

application/json application/scim+json

Scim user

SCIM user

GET/scim/directory/{directoryId}/Users/{userId}
1 2 3 4 curl --request GET \ --url 'https://api.atlassian.com/scim/directory/{directoryId}/Users/{userId}?attributes={attributes}' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 { "schemas": [ "<string>" ], "userName": "<string>", "emails": [ { "value": "<string>", "type": "<string>", "primary": true } ], "id": "<string>", "externalId": "<string>", "name": { "formatted": "<string>", "familyName": "<string>", "givenName": "<string>", "middleName": "<string>", "honorificPrefix": "<string>", "honorificSuffix": "<string>" }, "displayName": "<string>", "nickName": "<string>", "title": "<string>", "preferredLanguage": "<string>", "department": "<string>", "organization": "<string>", "timezone": "<string>", "phoneNumbers": [ { "value": "<string>", "type": "<string>", "primary": true } ], "meta": { "resourceType": "USER", "location": "<string>", "lastModified": "<string>", "created": "<string>" }, "groups": [ { "type": "<string>", "value": "<string>", "display": "<string>", "$ref": "<string>" } ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "organization": "<string>", "department": "<string>" }, "urn:scim:schemas:extension:atlassian-external:1.0": { "atlassianAccountId": "<string>" }, "active": true }
PUT

Update user via user attributes

Update the directory-based user information using the user attributes associated with their userId. User information is replaced attribute-by-attribute, with the exception of immutable and read-only attributes. Existing values of unspecified attributes are cleaned.

Request

Path parameters

directoryId

string

Required
userId

string

Required

Query parameters

attributes

string

excludedAttributes

string

Request bodyapplication/json application/scim+json

User information. The userName is a required field.

userName

string

emails

array<Scim user email>

name

Scim user name

displayName

string

nickName

string

title

string

preferredLanguage

string

department

string

organization

string

timezone

string

Responses

User has been updated successfully.

application/json application/scim+json

Scim user

SCIM user

PUT/scim/directory/{directoryId}/Users/{userId}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 curl --request PUT \ --url 'https://api.atlassian.com/scim/directory/{directoryId}/Users/{userId}' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "userName": "<string>", "emails": [ { "value": "<string>", "type": "<string>", "primary": true } ], "name": { "formatted": "<string>", "familyName": "<string>", "givenName": "<string>", "middleName": "<string>", "honorificPrefix": "<string>", "honorificSuffix": "<string>" }, "displayName": "<string>", "nickName": "<string>", "title": "<string>", "preferredLanguage": "<string>", "department": "<string>", "organization": "<string>", "timezone": "<string>", "phoneNumbers": [ { "value": "<string>", "type": "<string>", "primary": true } ], "active": true }'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 { "schemas": [ "<string>" ], "userName": "<string>", "emails": [ { "value": "<string>", "type": "<string>", "primary": true } ], "id": "<string>", "externalId": "<string>", "name": { "formatted": "<string>", "familyName": "<string>", "givenName": "<string>", "middleName": "<string>", "honorificPrefix": "<string>", "honorificSuffix": "<string>" }, "displayName": "<string>", "nickName": "<string>", "title": "<string>", "preferredLanguage": "<string>", "department": "<string>", "organization": "<string>", "timezone": "<string>", "phoneNumbers": [ { "value": "<string>", "type": "<string>", "primary": true } ], "meta": { "resourceType": "USER", "location": "<string>", "lastModified": "<string>", "created": "<string>" }, "groups": [ { "type": "<string>", "value": "<string>", "display": "<string>", "$ref": "<string>" } ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "organization": "<string>", "department": "<string>" }, "urn:scim:schemas:extension:atlassian-external:1.0": { "atlassianAccountId": "<string>" }, "active": true }
DEL

Deactivate a user

Deactivates a user from the directory by their userId, along with its group memberships. If the userId is linked to a managed Atlassian account, the account is deactivated. The user is not available for future requests until created with a new userId. Any future operation for the deactivated user returns the 404 (resource not found) error.

The deactivated user can be activated again via Atlassian Administration..

To deactivate the account instead, use the Update user by ID API. Update the op field to replace and value field to active:false within the operations request body.

Note: Executing this API call will result in the deletion of the SCIM record, and there is no method to reverse these changes except by creating a new SCIM record with Create a user API.

Request

Path parameters

directoryId

string

Required
userId

string

Required

Responses

User has been deactivated.

DEL/scim/directory/{directoryId}/Users/{userId}
1 2 3 curl --request DELETE \ --url 'https://api.atlassian.com/scim/directory/{directoryId}/Users/{userId}' \ --header 'Authorization: Bearer <access_token>'
PATCH

Update user by ID (PATCH)

Updates a user's information in the directory based on their userId via PATCH. Refer to Service Provider Configuration APIs for details on supported operations.

Request

Path parameters

directoryId

string

Required
userId

string

Required

Query parameters

attributes

string

excludedAttributes

string

Request bodyapplication/json application/scim+json

Patch op information

schemas

array<string>

operations

array<Operation for a Scim patch.>

Responses

User has been updated successfully.

application/json application/scim+json

Scim user

SCIM user

PATCH/scim/directory/{directoryId}/Users/{userId}
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 curl --request PATCH \ --url 'https://api.atlassian.com/scim/directory/{directoryId}/Users/{userId}' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "schemas": [ "<string>" ], "operations": [ { "op": "<string>", "path": "<string>", "value": { "array": true, "null": true, "valueNode": true, "containerNode": true, "missingNode": true, "object": true, "nodeType": "ARRAY", "pojo": true, "number": true, "integralNumber": true, "floatingPointNumber": true, "short": true, "int": true, "long": true, "double": true, "bigDecimal": true, "bigInteger": true, "textual": true, "boolean": true, "binary": true, "float": true } } ] }'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 { "schemas": [ "<string>" ], "userName": "<string>", "emails": [ { "value": "<string>", "type": "<string>", "primary": true } ], "id": "<string>", "externalId": "<string>", "name": { "formatted": "<string>", "familyName": "<string>", "givenName": "<string>", "middleName": "<string>", "honorificPrefix": "<string>", "honorificSuffix": "<string>" }, "displayName": "<string>", "nickName": "<string>", "title": "<string>", "preferredLanguage": "<string>", "department": "<string>", "organization": "<string>", "timezone": "<string>", "phoneNumbers": [ { "value": "<string>", "type": "<string>", "primary": true } ], "meta": { "resourceType": "USER", "location": "<string>", "lastModified": "<string>", "created": "<string>" }, "groups": [ { "type": "<string>", "value": "<string>", "display": "<string>", "$ref": "<string>" } ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "organization": "<string>", "department": "<string>" }, "urn:scim:schemas:extension:atlassian-external:1.0": { "atlassianAccountId": "<string>" }, "active": true }
GET

Get users

Get users from the specified directory. Filtering is supported with a single exact match (eq) against the userName and externalId attributes.

Note: While this API enables pagination, sorting functionality is not supported.

Request

Path parameters

directoryId

string

Required

Query parameters

attributes

string

excludedAttributes

string

filter

string

startIndex

integer

count

integer

Responses

Users have been returned successfully.

application/json application/scim+json

Scim user list response

SCIM user list response

GET/scim/directory/{directoryId}/Users
1 2 3 4 curl --request GET \ --url 'https://api.atlassian.com/scim/directory/{directoryId}/Users' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 { "schemas": [ "<string>" ], "totalResults": 196, "startIndex": 73, "itemsPerPage": 57, "Resources": [ { "schemas": [ "<string>" ], "userName": "<string>", "emails": [ { "value": "<string>", "type": "<string>", "primary": true } ], "id": "<string>", "externalId": "<string>", "name": { "formatted": "<string>", "familyName": "<string>", "givenName": "<string>", "middleName": "<string>", "honorificPrefix": "<string>", "honorificSuffix": "<string>" }, "displayName": "<string>", "nickName": "<string>", "title": "<string>", "preferredLanguage": "<string>", "department": "<string>", "organization": "<string>", "timezone": "<string>", "phoneNumbers": [ { "value": "<string>", "type": "<string>", "primary": true } ], "meta": { "resourceType": "USER", "location": "<string>", "lastModified": "<string>", "created": "<string>" }, "groups": [ { "type": "<string>", "value": "<string>", "display": "<string>", "$ref": "<string>" } ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "organization": "<string>", "department": "<string>" }, "urn:scim:schemas:extension:atlassian-external:1.0": { "atlassianAccountId": "<string>" }, "active": true } ] }
POST

Create a user

Creates a user in the directory. Note: An attempt to create an existing user will fail with a 409 (Conflict) error. Use this API to manage accounts outside your organization when assigning these users to SCIM groups. If there's already a managed Atlassian account associated with the specified email address on the Atlassian platform, the user in your identity provider will be connected or linked to the user in your Atlassian organization.

Request

Path parameters

directoryId

string

Required

Query parameters

attributes

string

excludedAttributes

string

Request bodyapplication/json application/scim+json

User information. The userName parameter is required.

userName

string

emails

array<Scim user email>

name

Scim user name

displayName

string

nickName

string

title

string

preferredLanguage

string

department

string

organization

string

timezone

string

Responses

User has been created successfully.

application/json application/scim+json

Scim user

SCIM user

POST/scim/directory/{directoryId}/Users
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 curl --request POST \ --url 'https://api.atlassian.com/scim/directory/{directoryId}/Users' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "userName": "<string>", "emails": [ { "value": "<string>", "type": "<string>", "primary": true } ], "name": { "formatted": "<string>", "familyName": "<string>", "givenName": "<string>", "middleName": "<string>", "honorificPrefix": "<string>", "honorificSuffix": "<string>" }, "displayName": "<string>", "nickName": "<string>", "title": "<string>", "preferredLanguage": "<string>", "department": "<string>", "organization": "<string>", "timezone": "<string>", "phoneNumbers": [ { "value": "<string>", "type": "<string>", "primary": true } ], "active": true }'
201Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 { "schemas": [ "<string>" ], "userName": "<string>", "emails": [ { "value": "<string>", "type": "<string>", "primary": true } ], "id": "<string>", "externalId": "<string>", "name": { "formatted": "<string>", "familyName": "<string>", "givenName": "<string>", "middleName": "<string>", "honorificPrefix": "<string>", "honorificSuffix": "<string>" }, "displayName": "<string>", "nickName": "<string>", "title": "<string>", "preferredLanguage": "<string>", "department": "<string>", "organization": "<string>", "timezone": "<string>", "phoneNumbers": [ { "value": "<string>", "type": "<string>", "primary": true } ], "meta": { "resourceType": "USER", "location": "<string>", "lastModified": "<string>", "created": "<string>" }, "groups": [ { "type": "<string>", "value": "<string>", "display": "<string>", "$ref": "<string>" } ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "organization": "<string>", "department": "<string>" }, "urn:scim:schemas:extension:atlassian-external:1.0": { "atlassianAccountId": "<string>" }, "active": true }