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

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 select your organization.
2. From the top menu select Security, then from left hand pane select Identity providers.
3. Choose the Directory Name for which you want to rotate or regenerate an API key.
4. Click on the three dots menu under the User provisioning section (on the bottom right hand side).
5. From the list select the Regenerate API key option.
6. Select Regenerate key.
7. Copy the value of Directory base URL and the API key to a safe place. Once you close the API key information screen, we won't show you this information again.
8. Select Done.

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/admin/v1/scim/<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

• 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 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 50,000 users for each group.

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