How to invite users to a Jira Cloud site and then add users to groups via REST API on an organization with the centralized organization experience
Platform Notice: Cloud Only - This article only applies to Atlassian products on the cloud platform.
Summary
This article provides a guide on how to invite users to a Cloud site using the Jira REST API. This article also provides guidance on how to add users to groups in the centralized user management experience using the Organizations REST API, particularly in situations where:
Users and groups are not provisioned via SCIM
The end users' Atlassian account(s) is not listed under Directory > Users page in admin.atlassian.com
The APIs mentioned in the document can be looped/called in a script to automate user invite tasks or add users to groups in bulk, but that will be out of scope for this document.
This KB only applies to the centralized user management experience
There are currently two different experiences for user management within admin.atlassian.com.
Go to Atlassian Administration. Select your organization if you have more than one. Then select Directory. If the Users and Groups lists are found here, then you are using the centralized user management.
Learn more about the centralized user management experience.
Solution
Pre-requisites
These instructions will only work if the organization has a Jira product - see: Invite a user for additional context
Authorization for the Organizations REST API is provided with a admin API key
Authorization for the Jira Cloud REST API is provided with a user API token
A user must be invited to the Cloud site before that user can be added to a group
Invite a user
Invite a user to the Directory > Users page by using the Create User API request. The API is a Jira Cloud API and thus, Jira needs to be added to the Cloud site before calls to this end point will be successful. This is an example call using cURL:
cURL: Create user API
curl --request POST \
--url 'https://<your_site_name>.atlassian.net/rest/api/3/user' \
--user '<admin_email_address>:<user_api_token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"emailAddress": "end_user@your_domain",
"products": []
}'The call is made to a specific Cloud site. As mentioned, the site must have Jira added as an app(product) on the site
A user with the appropriate permissions needs to be specified in the
userheader. Typically, this will be an organization admin or a user access admin. For more information, please see: What features are available to each admin role in Atlassian AdministrationInstructions on how to generate and use a user API token can be found here: Manage API tokens for your Atlassian account - direct link to your user API tokens: https://id.atlassian.com/manage-profile/security/api-tokens
The
emailAddressvalue is the email address of the end user being invitedSpecify
productsin the request body that the invited user should have access to. The array can be left empty if the end user should not have any app/product access - as shown in the example above. Alternatively, specify one or more of these apps/products in the array if required:jira-servicedesk
jira-product-discovery
jira-software
In order to specify a app/product, the app(product) needs to be added to the Cloud site
Example - the end user will receive Jira(Software) and Jira Service Management product access if specified as below:
Specify product
"products": ["jira-servicedesk", "jira-software"]
Add a user to a group
Once a user has been invited to the Users page, the end user can be added to a group by using this endpoint: Add user to group. This is an example using cURL:
cURL: Add user to group
curl --request POST \
--url 'https://api.atlassian.com/admin/v1/orgs/<your_organization_id>/directory/groups/<group_id>/memberships' \
--header 'Authorization: Bearer <admin_api_key>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"account_id": "<end_user_atlassian_account_id>"
}'The url header requires the organization ID and group ID values
To find the organization ID, navigate to https://admin.atlassian.com, select the relevant organization and in the URL of the page, the organization ID will be displayed. Example URL:
|
To find the group IDs, call this API: get groups in an organization and the group IDs will be returned in the response. Alternatively, navigate to Directory > Groups and select the group you'd like to add the user(s) to. In the URL of the page, the group ID will be displayed. Example:
|
The user's Atlassian account ID can be found by taking an export of the accounts on the Users page:Export users from a site
Was this helpful?