/
Making Service API calls in Automation Rules

Making Service API calls in Automation Rules

Owned by Rick Munoz
Last updated: Jan 20, 2025
4 min read

The app provides a Service API for making Entra ID changes to users and groups. This API is meant to be called from Automation Rules using the “Send Web Request” action. This action looks like this in the rule:

image-20250116-224257.png

If you are unfamiliar with the Send Web Request action, you can find out more from these pages:

Here’s an example of a configured Send Web Request action for enabling a user account:

image-20250116-225506.png

Setting up a Send Web Request action

Here’s how to set up a Send Web Request action to the Service API:

  • Get the URL, request body structure, and the API key for the specific call. See this page for how to find this information: Using the Service API tab (A simple way of getting the URL is to copy it from the sample curl statement on that page.)

  • Enter the URL into the Web request URL field

  • Select POST for the HTTP Method

  • Set the Web request body to “Custom data”

  • Enter the request body structure/template into the Custom data field

  • Check the “Delay execution…” checkbox to be ON

  • Check the “Continue running the rule…” checkbox to be ON

  • Add the three headers, using the API Key as the value for the header “x-automation-key”

     

    image-20250116-225718.png

    We checked the “Hidden” checkbox for the x-automation-key value in this example.

  • Update the request body to contain the correct data for the specific API call. In the example above, the call specifies that the Entra ID user “testsupport1” should have its account enabled.

Using the web response body and values

Here is the description on how to access the web response values, including the status code:

To access the response data you will need to select the 'Delay execution' checkbox above.

On successful web request, you will be able access response data using the following smart values:

  • {{webResponse.status}} returns the response code e.g. 200

  • {{webResponse.statusCategory}} returns the category of the response status - INFO, SUCCESS, REDIRECT, CLIENT_ERROR, SERVER_ERROR, OTHER

  • {{webResponse.headers}} returns the response headers that you can access using dot notation e.g. {{webResponse.headers.Content-Type}}

  • {{webResponse.body}} returns the response body, if the body is a JSON object then you can access values using dot notation e.g. {{webResponse.body.name}}

  • {{webResponses}} returns a list of the 10 most recent responses this rule received. E.g. {{webResponses.last.body}}

You can check if the API call was successful in two ways:

  • Checking if the value of {{webResponse.status}} is 200.

  • Seeing if the string SUCCESS is in the {{webResponse.statusCategory}} variable, like this:

image-20250117-163441.png

For the Add User and Reset Password Service API calls, the webResponse body may contain the system-generated temporary password that needs to be securely communicated to the end user. Your automation rule needs to extract that password from the response body for passing on securely.

In most cases, receiving a status code other than 200 indicates a problem with the API call. In these cases, use an ELSE clause to log the API error information (including {{webResponse.body}}) so that an administrator can diagnose the issue.

See the next section on handling non-success response codes from each Service API call.

API Call Error/Exception Handling

When calling the Service API from an automation rule, we strongly recommend that the next step in the rule is to check the return code status of the API call, and handle the cases where the return code is not 200 ie., ‘success’.

 

There are scenarios, however, when a status code other than 200 may indicate that the API call has encountered a common situation. These scenarios include:

  • Getting back a 400 CLIENT_ERROR status from an “Add to group” or “Remove from group” API call. These may indicate that the user is already a member of the group (when trying to Add) or not a member of a group (when trying to Remove)

    • For example, the response body for adding a user that is already in the group is: {error=User is already a member of the group}

  • Getting back a 400 CLIENT_ERROR when trying to add/remove from a group that doesn’t exist or isn’t serviceable.

    • The response body for a non-existent group will be {error=Group not found}.

    • The response body for a non-serviceable group will be {error=Group <group name> is not a serviceable group or does not exist}.

  • Getting a 400 CLIENT_ERROR status returned when adding a user and providing a password that does not meet the password complexity requirements defined in Entra ID. Here’s the example response body for that scenario:

    • {error={"error":{"code":"Request_BadRequest","message":"The specified password does not comply with password complexity requirements. Please provide a different password.","innerError":{"date":"2025-01-17T17:17:15","request-id":"2218484a-839e-4947-aa9c-187440644f07","client-request-id":"2218484a-839e-4947-aa9c-187440644f07"}}}}

In the above example scenarios, the error handling actions should be more informative about the issue, perhaps extracting and formatting the message in a comment or sending an email to report the issue.

 

Related content