Using the Service API tab

The primary mechanism for using the Entra ID Connect app functionality is to call the Service API provided by the app. This allows you to build automation rules that make the web service call to the API to perform the Entra ID actions for specific scenarios.

The URLs provided within this tab (and its subtabs) are unique to your Atlassian cloud site. They cannot be called from any other Atlassian site, nor can they be called from outside of the Atlassian cloud.

Here are the sections in this page:

1 Web Service calls to the App Service API – Common Elements
2 Generating the API Key to use
3 List Serviceable Groups API call
4 Add User API Call
5 Update User API calls (including Enable/Disable User)
6 Reset Password API Call
7 Change Group Membership API Calls

Web Service calls to the App Service API – Common Elements

For all the Service API endpoints described below, the HTTP calls will have the same common elements:

All Service API calls are POST HTTP command calls
The URI is the same for all calls. This is the generated URI shown to you on the tabs. It will look like this: https://d0883f75-347c-42d0-9766-38eeca289a51.hello.atlassian-dev.net/x1/hCxesAz1RL0qpw2qCm06hf7W9H4

The identifiers before the hello and after the x1 will be unique for your site

Three headers are required:
- Content-Type: Application/JSON
- x-automation-source: Atlassian-Automation
- x-automation-key: <current generated key>
The Post body JSON will have two values:
- “route” - this indicates what operation is requested
- “data” - this contains the data for the specific operation

If you are unfamiliar with how to make a web service API call from an automation rule, you can find out more about this on these pages:

You can download a Swagger document for each individual API endpoint by clicking on the respective “Swagger Doc” button shown. The downloaded JSON file can then be imported into SwaggerEditor (using File>Import menu) to be viewed using the Swagger documentation format.

Generating the API Key to use

The URLs are secured through the use of a generated API Key. Please keep this API Key secure as it, along with the URLs, gives anyone who can build automation rules to make Entra ID changes.

Click the “Generate Key” button on the Service API Key tab to generate the key.

The page will then show the generated API key for use.

The API Key can be regenerated at any time. However, doing this requires updating any reference to that API Key in automation rules calling the app’s Service API. SeeImportant Security Considerations for options for managing the API Key.

List Serviceable Groups API call

Using the route “getservicablegroups,” this API call returns the list of serviceable Entra ID groups set up in the Assets schema.

The response body of the call will return a JSON object that contains an array of serviceable groups:

{message=Serviceable groups: [{"label":"Test","value":"Test"}]}

If the array is empty, no groups have been set up as serviceable. See this page on marking groups as serviceable: Step 5: Set up Serviceable Groups

Add User API Call

The API call for adding a user to Entra ID has a route of “adduser” and accepts a JSON object that contains fields to direct the addition and the attributes values for this new user.

If you specify a value of false for the systemgeneratedPassword field, you must provide a password that meets the minimum password complexity requirements defined in your Entra ID configuration.

When the call is successful, the response body of the web services call will include the generated password. Securely extract the password from the response body and transmit it to the end user.

Here’s an example of the response body:

{message=Reset account: testsupport1@t4spartners.com New Password is: UdNv,3dsenKAj*;(k83}

Update User API calls (including Enable/Disable User)

The API call to update an Entra ID user has the route “updateuser” and requires the userPrincipalName of the user to update.

The attribute values to update should be included in the request body. If a user attribute is not specified in the request body, that attribute will not be changed.

To Enable or Disable a user’s Entra ID account, specify the “accountEnabled” attribute with the value True to enable the account and the value False to disable the account.

Upon the successful call, the response body of the API call will be:

{message=User updated successfully}

Reset Password API Call

The API call to reset a user’s password (route: “resetpwd”) takes one attribute in addition to the userPrincipalName:

forceChangePasswordNextSignIn - when set to true, the user must change the password upon the next Entra ID sign-in attempt.

When the call is successful, the response body will contain the newly generated password for that user. It will take the following format:

{message=Reset account: <upn> New Password is: <password>}

The automation rule is responsible for extracting the new password from the response body and securely transmitting it to the appropriate person(s).

Here are some possible methods to consider in communicating that new password:

Send via email to the user’s manager (if that information is available)
Add a comment to the issue that includes the temporary password. This is useful if a Service Desk Agent needs to verbally provide the password to an authenticated user over the phone.

Change Group Membership API Calls

The API call for adding or removing an Entra ID user from a serviceable group takes a groupName and the userPrincipalName in the request body. The route for adding is “addusertoserviceablegroup,” and for removing, it is “removeuserfromservicablegroup.”

When adding a user to a group and the user specified is already a member, the call will return a 401 Bad request response, with a comment indicating that the user is already a member of that group.

When removing a user from a group who is not a member, the call will return a 401 Bad request response, indicating that the user is not in the group.

Marketplace Apps