Rate this page:

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

Rate this page: