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

The User provisioning REST API integrates your organization with an identity provider. Use this API to:

• Create, get and update users
• Create, get and update groups by ID
• Get schemas and resources

To manage accounts, use the User management REST API.

To manage your organization, use the Organizations REST API.

Directory Token Authentication

To manage users and groups using the User Provisioning APIs, you will require an API key (distinct from your Cloud admin API key). This unique key grants you full administrative control over your organization's directory, enabling you to create and update user attributes as well as modify user group memberships. To authenticate your script and administer your directory, utilize this API key as a Bearer access token.

Furthermore, each directory is distinguished by a Unique ID, specifically the directoryId found after 'directory/' in the Directory's base URL. For instance, if the Directory base URL is https://api.atlassian.com/scim/directory/abcdeg1234, the directoryId is abcdeg1234.

Learn more about Configuring user provisioning.

To make requests to the API with the client/tool of your choice, follow these steps to create an API key and obtain the directory ID

1. Go to admin.atlassian.com and select your organization.
2. From the top menu, navigate to Security, and then select Identity providers from the left-hand panel.
3. Choose the relevent Directory.
4. Click the three dots menu located under the User Provisioning section (bottom right-hand side).
5. Select Regenerate API key.
6. Select Regenerate key.
7. Copy the value of Directory base URL and the API key and keep them in a safe place. We won't show them to you again.
8. Click Done to end the process.

Organization API Token Authentication

To access certain Admin APIs w/ relation to SCIM, you can use the Organization API token. Create an api key and get the organization ID. Note that this is the same API key that's generated for the Organizations REST API.

Group and User SCIM URI

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

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

Org API Token URI

1
2
https://api.atlassian.com/admin/user-provisioning/<resource-name>

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.

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

User limitations

• Deleting a managed user account via the user provisioning API is not supported. The DELETE operation deactivates the managed user account in Adminhub, which is the same as setting the active flag to false.
• There is a 150,000 user limit per directory. This limit is enforced for compatibility with products that have an upper bound for total supported users. Also, you can only sync up to 35,000 users for each group. In case you want to sync upto 50,000 users per group, contact support

Group limitations

Note: If you have the improved user management experience, any references in the documentation below to "your site" or "your organization's sites" are now "your organization".

• When you create a group that has the same name as an existing group in the organization, the group creation fails with a 409 (conflict) error.
• You cannot create a group with same name as default access group or Atlassian built-in groups. In case you'll try to do this, you'll see a success message in the API response but the group will not be synced to your site. For more information about default and Atlassian built-in group refer Default groups and permissions
• 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