About the user provisioning REST API

Use this REST API to integrate your organization with an identity provider.

Authentication and authorization

To manage users and groups with the user provisioning REST API, you need an API key separate from your Cloud admin API key. This key gives full administrative access to your organization's directory, allowing the API client to create and update user attributes and change user group membership.

See Configure user provisioning.

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

If you need to "rotate" or regenerate an API key, use the following steps:

  1. Go to admin.atlassian.com and click your organization.
  2. Click Directory, then click User provisioning.
  3. Click the Directory tab, then click the Regenerate API key button.
  4. Click Regenerate key.
  5. Copy the organization ID and the API key to a safe place. Once you close the API key information screen, we won't show you this information again.
  6. Click Done.

Version and URI

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

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

Pagination

The user provisioning REST API uses pagination to conserve server resources and limit response size. If there are more results available after the current page, a link to the next page of results is included in the JSON. You can use the cursor parameter to set a specific starting point for the results.

Status codes

We follow the standard HTTP status code definition. See W3C Status Code Definitions for the detailed code definitions.

Limitations

User limitations

  • A user account only can only be created if it has an email address on a domain you have verified.
  • Deleting a user account via the user provisioning API is not supported. The DELETE operation deactivates the user account, which is the same as setting the active flag to false.
  • There is a 5000-user limit per directory. This limit is enforced for compatibility with products that have an upper bound for total supported users.

Group limitations

  • When you sync a group that has the same name as an existing group in the organization, the group sync fails with a 409 (conflict) error.
  • If the API creates a group in the organization's directory that has the same name of a site's group (e.g. confluence-users), the API successfully creates the group in the directory but fails to propagate the group to the organization's sites. You'll see this event in the audit log.
  • Changing group names isn't supported. Renaming groups after they've synced to your Atlassian organization isn't supported in this release of User Provisioning API. This is because some parts of the products rely on group names and changing the group name would result in users not being able to interact with the products correctly. To rename a group, create a new group with the desired name, update membership, and then delete the old group.

Authorization limitations

  • You can only view and store the Access Token (API key) during directory creation. If you lose your token, you can regenerate a new one. See Authentication and authorization

Users

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 a user by ID

GET /scim/directory/{directoryId}/Users/{userId}

Get a user from a directory by userId.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory Id

userId Required

string

The user ID

Query parameters
attributes

string

Resource attributes to be included in response. Mutually exclusive with excludedAttributes. Example: userName,emails.value

excludedAttributes

string

Resource attributes to be excluded from response. Mutually exclusive with attributes. Example: timezone,emails.type,department

Example

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'

Responses

User has been returned successfully.

Content typeValue
application/json

Scim user

application/scim+json

Scim user

Update user via user attributes

PUT /scim/directory/{directoryId}/Users/{userId}

Updates a user's information in a directory by userId via user attributes. User information is replaced attribute-by-attribute, with the exception of immutable and read-only attributes. Existing values of unspecified attributes are cleaned.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory Id

userId Required

string

User ID

Query parameters
attributes

string

Resource attributes to be included in the response. Mutually exclusive with excludedAttributes. Example: userName,emails.value

excludedAttributes

string

Resource attributes to be excluded in the response. Mutually exclusive with attributes. Example: timezone,emails.type,department

Body parameters
Content typeValue
application/json

Scim user

application/scim+json

Scim user

Example

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
}'

Responses

User has been updated successfully.

Content typeValue
application/json

Scim user

application/scim+json

Scim user

Deactivate a user

DELETE /scim/directory/{directoryId}/Users/{userId}

Deactivate a user by userId. The user is not available for future requests until activated again. Any future operation for the deactivated user returns the 404 (resource not found) error.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory Id

userId Required

string

User Id

Example

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

Responses

User has been deactivated.

Update user by ID (PATCH)

PATCH /scim/directory/{directoryId}/Users/{userId}

This operation updates a user's information in a directory by userId via PATCH. Refer to GET /ServiceProviderConfig for details on the supported operations.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory Id

userId Required

string

User Id

Query parameters
attributes

string

Resource attributes to be included in the response. Mutually exclusive with excludedAttributes. Example: userName,emails.value

excludedAttributes

string

Resource attributes to be included in the response. Mutually exclusive with attributes. Example: timezone,emails.type,department

Body parameters
Content typeValue
application/json

Request payload to patch.

application/scim+json

Request payload to patch.

Example

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
      }
    }
  ]
}'

Responses

User has been updated successfully.

Content typeValue
application/json

Scim user

application/scim+json

Scim user

Get users

GET /scim/directory/{directoryId}/Users

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

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory Id

Query parameters
attributes

string

Resource attributes to be included in response. Mutually exclusive with excludedAttributes. Example: userName,emails.value

excludedAttributes

string

Resource attributes to be excluded from response. Mutually exclusive with attributes. Example: timezone,emails.type,department

filter

string

Filter for userName or externalId. Example: userName eq "Atlassian"

startIndex

integer

A 1-based index of the first query result.

Default: 1, Format: int32
count

integer

Desired maximum number of query results in the list response page.

Format: int32

Example

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'

Responses

Users have been returned successfully.

Content typeValue
application/json

Scim user list response

application/scim+json

Scim user list response

Create a user

POST /scim/directory/{directoryId}/Users

Create a user in a directory. An attempt to create an existing user fails with a 409 (Conflict) error. A user account can only be created if it has an email address on a verified domain. If a managed Atlassian account already exists on the Atlassian platform for the specified email address, the user in your identity provider is linked to the user in your Atlassian organization.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory Id

Query parameters
attributes

string

Resource attributes to be included in response. Mutually exclusive with excludedAttributes. Example: userName,emails.value

excludedAttributes

string

Resource attributes to be excluded from response. Mutually exclusive with attributes. Example: timezone,emails.type,department

Body parameters
Content typeValue
application/json

Scim user

application/scim+json

Scim user

Example

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
}'

Responses

User has been created successfully.

Content typeValue
application/json

Scim user

application/scim+json

Scim user

Groups

Get a group by ID

GET /scim/directory/{directoryId}/Groups/{id}

Get a group from a directory by group ID.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory Id

id Required

string

Group Id

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/scim/directory/{directoryId}/Groups/{id}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Group has been returned successfully.

Content typeValue
application/json

Scim group

application/scim+json

Scim group

Update a group by ID

PUT /scim/directory/{directoryId}/Groups/{id}

Update a group in a directory by group ID.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

id Required

string

Group Id

Body parameters
Content typeValue
application/json

Scim group

application/scim+json

Scim group

Example

1
2
3
4
5
6
7
8
curl --request PUT \
  --url 'https://api.atlassian.com/scim/directory/{directoryId}/Groups/{id}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "displayName": "<string>"
}'

Responses

Group has been updated successfully.

Content typeValue
application/json

Scim group

application/scim+json

Scim group

Delete a group by ID

DELETE /scim/directory/{directoryId}/Groups/{id}

Delete a group from a directory. An attempt to delete a non-existent group fails with a 404 (Resource Not found) error.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory Id

id Required

string

Group Id

Example

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

Responses

Group has been deleted successfully.

Update a group by ID (PATCH)

PATCH /scim/directory/{directoryId}/Groups/{id}

Update a group's information in a directory by groupId via PATCH. You can use this API to manage group membership.

Note: Renaming groups after they've synced to your Atlassian organization isn't supported in this release of the User Provisioning API. To rename a group, create a new group with the desired name, update membership, and then delete the old group.

Example

Some HTTP headers omitted and JSON payloads formatted for readability.

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
70
71
# Request
PATCH /scim/directory/2fb21891-7bee-4c2d-a61a-ade3834c8b2b/Groups/50202593-bc47-45df-8fa0-3f63343aa3c1 HTTP/1.1
Accept: application/scim+json
Accept-Charset: utf-8
Content-Type: application/scim+json; charset=utf-8
Authorization: Bearer 0j6lDgrjU7HmGagocgLe
Host: api.atlassian.com

{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
   ],
   "Operations":[
      {
         "op":"add",
         "path":"members",
         "value":[
            {
               "value":"c6993c94-dbda-40f1-b6f0-18c855522ade",
               "display":"dave.meyer@demotime.authteam.com"
            },
            {
               "value":"f0ae48f7-1466-445e-85ea-e83ef754aefd",
               "display":"lingbo.lu@demotime.authteam.com"
            },
            {
               "value":"432d6f10-2e28-454e-be99-0f8c732a046f",
               "display":"joanna@demotime.authteam.com"
            }
         ]
      }
   ]
}

# Response
HTTP/1.1 200
Content-Type: application/scim+json

{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:Group"
   ],
   "id":"50202593-bc47-45df-8fa0-3f63343aa3c1",
   "displayName":"demotime-confluence-users",
   "members":[
      {
         "type":"User",
         "value":"f0ae48f7-1466-445e-85ea-e83ef754aefd",
         "display":"lingbo.lu@demotime.authteam.com",
         "$ref":"https://api.atlassian.com/scim/directory/2fb21891-7bee-4c2d-a61a-ade3834c8b2b/Users/f0ae48f7-1466-445e-85ea-e83ef754aefd"
      },
      {
         "type":"User",
         "value":"c6993c94-dbda-40f1-b6f0-18c855522ade",
         "display":"dave.meyer@demotime.authteam.com",
         "$ref":"https://api.atlassian.com/scim/directory/2fb21891-7bee-4c2d-a61a-ade3834c8b2b/Users/c6993c94-dbda-40f1-b6f0-18c855522ade"
      },
      {
         "type":"User",
         "value":"432d6f10-2e28-454e-be99-0f8c732a046f",
         "display":"joanna@demotime.authteam.com",
         "$ref":"https://api.atlassian.com/scim/directory/2fb21891-7bee-4c2d-a61a-ade3834c8b2b/Users/432d6f10-2e28-454e-be99-0f8c732a046f"
      }
   ],
   "meta":{
      "resourceType":"Group",
      "location":"https://api.atlassian.com/scim/directory/2fb21891-7bee-4c2d-a61a-ade3834c8b2b/Groups/50202593-bc47-45df-8fa0-3f63343aa3c1",
      "lastModified":"2018-09-26T17:49:09.420654Z",
      "created":"2018-09-26T17:41:35.49073Z"
   }
}
OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory ID

id Required

string

Group ID

Body parameters
Content typeValue
application/json

Request payload to patch.

application/scim+json

Request payload to patch.

Example

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}/Groups/{id}' \
  --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
      }
    }
  ]
}'

Responses

Group has been updated successfully.

Content typeValue
application/json

Scim group

application/scim+json

Scim group

Get groups

GET /scim/directory/{directoryId}/Groups

Get groups from a directory. Filtering is supported with a single exact match (eq) against the displayName attribute. Pagination is supported. Sorting is not supported.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Directory Id

Query parameters
filter

string

Filter for displayName. Example: displayName eq "SCIM_GROUP"

startIndex

integer

A 1-based index of the first query result.

Default: 1, Format: int32
count

integer

Desired maximum number of query results in the list response page.

Format: int32

Example

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

Responses

Groups have been returned successfully.

Content typeValue
application/json

Scim group list response

application/scim+json

Scim group list response

Create a group

POST /scim/directory/{directoryId}/Groups

Create a group in a directory. An attempt to create a group with an existing name fails with a 409 (Conflict) error.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Body parameters
Content typeValue
application/json

Scim group

application/scim+json

Scim group

Example

1
2
3
4
5
6
7
8
curl --request POST \
  --url 'https://api.atlassian.com/scim/directory/{directoryId}/Groups' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "displayName": "<string>"
}'

Responses

Group has been created successfully.

Content typeValue
application/json

Scim group

application/scim+json

Scim group

Schemas

Get all schemas

GET /scim/directory/{directoryId}/Schemas

Get all SCIM features metadata. Filtering, pagination and sorting are not supported.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Example

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

Responses

SCIM features metadata has been returned successfully.

Content typeValue
application/json

string

application/scim+json

string

Get user schemas

GET /scim/directory/{directoryId}/Schemas/urn:ietf:params:scim:schemas:core:2.0:User

Get the user schemas from the SCIM provider. Filtering, pagination and sorting are not supported.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/scim/directory/{directoryId}/Schemas/urn:ietf:params:scim:schemas:core:2.0:User' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

SCIM features metadata has been returned successfully.

Content typeValue
application/json

string

application/scim+json

string

Get group schemas

GET /scim/directory/{directoryId}/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group

Get the group schemas from the SCIM provider. Filtering, pagination and sorting are not supported.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/scim/directory/{directoryId}/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

SCIM features metadata has been returned successfully.

Content typeValue
application/json

string

application/scim+json

string

Get user enterprise extension schemas

GET /scim/directory/{directoryId}/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Get the user enterprise extension schemas from the SCIM provider. Filtering, pagination and sorting are not supported.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/scim/directory/{directoryId}/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

SCIM features metadata has been returned successfully.

Content typeValue
application/json

string

application/scim+json

string

Get feature metadata

GET /scim/directory/{directoryId}/ServiceProviderConfig

Get metadata about the supported SCIM features. This is a service provider configuration endpoint providing supported SCIM features. Filtering, pagination and sorting are not supported.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Example

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

Responses

SCIM features metadata has been returned successfully.

Content typeValue
application/json

string

application/scim+json

string

Service Provider Configuration

Get resource types

GET /scim/directory/{directoryId}/ResourceTypes

Get types of resources available on a SCIM service provider (e.g., Users and Groups). This is used to get all resources of the SCIM provider. Filtering, pagination and sorting are not supported.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Example

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

Responses

SCIM features metadata has been returned successfully.

Content typeValue
application/json

string

application/scim+json

string

Get user resource types

GET /scim/directory/{directoryId}/ResourceTypes/User

Retrieve user resource types from the SCIM service provider. Filtering, pagination and sorting are not supported.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/scim/directory/{directoryId}/ResourceTypes/User' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

SCIM features metadata has been returned successfully.

Content typeValue
application/json

string

application/scim+json

string

Get group resource types

GET /scim/directory/{directoryId}/ResourceTypes/Group

Retrieve group resource type of this SCIM service provider. Filtering, pagination and sorting are not supported.

OAuth scopes required
None

Request

Path parameters
directoryId Required

string

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/scim/directory/{directoryId}/ResourceTypes/Group' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

SCIM features metadata has been returned successfully.

Content typeValue
application/json

string

application/scim+json

string