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

About the user provisioning REST API

Postman Collection

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.

Authentication and authorization

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.

Version and URI

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:


Org API Token URI



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


User limitations

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

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: