Integration Builder security enhancements

The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

We've made some exciting new enhancements to the Integration Builder that will improve integration security, and give you finer control over how to authenticate and track interactions between your applications and xMatters.

These changes will affect some of your existing outbound integrations, and ALL of your existing inbound integrations. 

Don't worry! Your integrations will continue to work as implemented, but at some point soon you will want to take advantage of the increased security and additional options that the new functions provide. 

Note: If you make any changes to an existing inbound integration, you will be prompted to select one of the new authentication methods before you can access the transformation scripts. 


We've been implementing these changes in stages over the past few months, with the latest features added during the Galaxity release. Here's what's changed:

  • You can now set authentication for inbound integrations separately for each integration, and there are four different authentication options to choose from. 
  • All inbound integrations are now authorized according to the plan and form permissions (i.e., the requesting user must have access permission to the plan, and sender permission to the form).
  • All outbound integration script requests are now authorized using the account and permissions of the user who initiated the integration.  

Inbound integration authentication

Previously, you could enable or disable authentication for all of the inbound integrations within a communication plan on the Integration Builder tab. Enabling the option would generate a randomized user name and password (essentially an API key and secret) that you could submit as credentials for any request, using basic HTTP authentication.

You must now choose from one of the following authentication options when configuring each inbound integration:

  • URL Authentication: When you select this method, xMatters generates an API key unique to you (i.e., the logged-in user), and appends it to the integration URL. Any requests submitted via this URL will have the same permissions as you in xMatters (though the URL does NOT grant permission to log into the web user interface).
  • Basic Authentication: This requires the calling system to store the credentials of an xMatters user. Any user who has permission to access this integration can authenticate the request using HTTP Basic Authentication and their username and password. If the user updates their password in xMatters, you must also update the credentials in the calling system. These credentials can also be used to log in to the xMatters user interface (if the user has permission to access it, of course), and will be subject to password expiry if enabled for your organization.
  • API Key: This method works similar to the previous inbound integration authentication option in that it generates a unique API key and randomized secret password, but the API key and secret are now specific to this inbound integration and the logged-in user. The API key and secret cannot be used to log in to the xMatters web user interface, and cannot be used to trigger any other inbound integration, even those on the same plan.
  • OAuth: This method uses xMatters access tokens and client IDs based on the xMatters OAuth authentication feature to authorize incoming requests. For more information about using OAuth with xMatters, see OAuth authentication.

For more information, and instructions on how to configure each of these options, refer to the xMatters On-Demand online help

Accessing the new feature

If you go into the Integration Builder after the recent Galaxity update, and expand the list of inbound integrations, you will notice a new icon and warning message beside your inbound integrations:

InboundIntegrationAuthPrompt.pngIf you then open the inbound integration to edit it, you'll see the new authentication options:


You will need to select a new method, and then update the endpoints in your calling system and scripts to make sure they are targeting the correct integration and using the right credentials.

Note: If you do not edit the integration, it will continue to function normally. However, you must select one of the new authentication methods if you want to modify the scripts or update any other settings.

Updating your inbound integrations

Lets say you've gone into your Integration Builder and noticed the little orange icons. So now what?

Well, you will first need to decide which authentication method works best for you and your integrations. You may decide to use different methods for different applications or different communication plans, or even for different inbound integrations within the same plan.

For this exercise, however, we're going to recommend that you use the API Key authentication for several reasons:

  • URL Authentication should really only be used if your calling system does not have the ability to include authentication headers in the request.
  • You've been following our integration guides when implementing your integrations, of course, and have a separate integration user (with the REST Web Service User role) assigned to the xMatters endpoint.
  • You don't want to store the xMatters credentials for your integration user in a third-party system.

So here's how to update your system and your inbound integrations to use the API Key authentication method.

For the highest availability of your systems while making these changes, have your calling system ready to modify. You will need to update the HTTP request to use authentication headers, but if you have the calling system open, you can copy and paste the credentials directly from the configuration screen in xMatters and update both systems simultaneously.

Step One: Update your integration user

To get an API key and secret for your integration user, you will need to log into xMatters as that user, but the default REST Web Service User role does not include the permissions necessary to log in to the web user interface or to modify inbound integration. Some integrations, such as ServiceNow, require you to assign additional roles to your integration user, but let's assume for now that your user has only the REST Web Service User role and cannot log in to xMatters.

To change this, login to xMatters as a supervisor or administrator and locate your integration user. On the Roles tab in their user profile, add the following roles:

  • Standard User: This will give your user permission to log into xMatters.
  • Limited Developer: This will give your user permission to access the Developer tab and the Integration Builder.

Be sure to save your changes!

Make sure you have the correct username and password for your integration user - you're going to need them in a minute.

Step Two: Confirm access permissions

Now is a good time to make sure your plans and forms are set up to allow your integration user to initiate integrations properly. 

  1. Navigate to the Developer tab, and find the communication plan for your integration. Click Edit > Access Permissions.


  1. In the Communication Plan Access Permissions dialog box, do one of the following:
    • Select the Accessible by All check box. 
    • Type "REST" into the search field and then select the REST Web Service User role when it appears in the drop-down list.
    • Start typing the name of your integration user into the search field. When the user appears in the drop-down list, select their name.
  2. Click Save Changes, and then click Edit > Forms.
  3. For each form in the plan that you want the integration user to be able to initiate, click the status button (which probably says something like "Web Service Only" or "Web UI and Web Service", and select Sender Permissions.


  1. In the Form Sender Permissions dialog box, do one of the following:
    • Type "REST" into the search field and then select the REST Web Service User role when it appears in the drop-down list.
    • Start typing the name of your integration user into the search field. When the user appears in the drop-down list, select their name.

Step Three: Generate your API key and secret

Now log out of xMatters and log back in using your integration user's credentials. After authenticating, all actions will be performed by this user, so you need to update the permissions on all the downstream integration parts.

  1. Navigate to the Developer tab, and into the Integration Builder for your integration's communication plan.
  2. Expand the list of inbound integrations, and click the name of the integration service you want to modify.
  3. On the inbound integration's details page, scroll down to the Select authentication method section, and select API Key in the drop-down list.


  1. Do one of the following:
    • Copy the API Key and Secret values to a text file for temporary safekeeping.
    • Copy and paste the API Key and Secret values directly into the appropriate fields within your calling system.
  2. To save your changes, click Update Inbound Integration.

Repeat these steps for each inbound integration that you want to configure for your integration user. (You may notice that the API Key is the same for all inbound integrations that you configure - this is because the key is tied to the logged-in user.)

When you have finished updating the integrations you want to change, make sure you log the integration user out of xMatters.

Step Four: Update your integrated systems

You can now update your calling systems (if you haven't already), to use authentication headers within the HTTP request.

Some pointers:

Outbound integration authentication

Another security enhancement is a change to how "Run a script" outbound integrations authenticate with xMatters:

Events initiated using any method other than an inbound integration will now authenticate outbound integration script requests using the account of the user who initiated the event.

Events initiated via an inbound integration use the same credentials that are used to initiate the integration, as specified by the authentication method configured on the inbound integration.

For example, let's say you inject an event into xMatters via the POST form trigger, and the communication plan you target includes an outbound integration that is configured to initiate a new conference bridge event when a user responds with a specific response choice. When triggered, the outbound integration will attempt to initiate that event using your credentials.

If the event initiator doesn't have the same permission levels as the account you expected to authenticate the requests in your outbound integration scripts, then the request won't be able to execute the required tasks. The script will still run and execute any of the requests for which the initiator DOES have the correct permission levels, but you might encounter an error in your integration's Activity Stream with a statusCode of 403, and a statusMessage of FORBIDDEN. The reason give will be similar to:

UNAUTHORIZED_ACCESS_ERROR: User does not have the permission to access this service/functionality.

Here's what that message looks like in the Activity Stream:


This issue could affect:

  • events initiated from within the xMatters mobile app, or by using the web user interface (i.e., the Messaging tab)
  • events triggered via the email form initiation feature
  • events injected via the REST POST form trigger 

Any of these events that target xMatters endpoints within their outbound integration scripts will use the permissions of the initiating user.

As mentioned, events that are initiated using an inbound integration use the credentials specified on the inbound integration, and not the xMatters endpoint as previously configured. Speaking of which...

The xMatters endpoint

The original implementation of the Integration Builder workflow required that you configure an xMatters endpoint that specified a user account to use when the integrations for that form needed to authenticate a request with xMatters. You could then target the xMatters endpoint from your outbound integration scripts with API requests to perform actions in xMatters, such as creating a device, retrieving a list of users, or initiating another event. 

The problem with this approach is that it automatically applied the same permissions (and the same initiator ID) to every request made to xMatters from the Integration Builder. The new authentication methods ensure that every request that enters the system has only the permissions assigned to the user making the request. (Once you have configured all of the inbound integrations in your system to use one of the new authentication methods, the "owner" of the xMatters endpoint will no longer have any effect; the setting will be removed in a future release of xMatters.)

Best practices

The best approach is mostly just making sure that you've thought through the implications of your integrations, and considered any potential differences in permission levels.

Here are some specific places you can check to make sure that your integrations won't run into any issues (for more information about how to perform any of these checks, click the link in each step):

  1. Review the authentication options detailed in the online help for inbound integrations, and decide which authentication method best suits your requirements.
    • Remember that both the URL Authentication and API Key options create credentials based on the logged-in user. If you want to submit requests based on a specific integration user's permissions, you must log in as that user when configuring the inbound integration (or choose the Basic Authentication option, and store their credentials on the calling system).
  2. Check the Sender Permissions and Access Permissions you currently have in place on your forms.
    • For inbound integrations, event initiation will fail if the authenticating user does not have both access to the plan AND permission to send messages for a form.
    • You may also need to adjust the sender permissions if you are starting xMatters events using your outbound integrations so that the user who started the original event can initiate the forms referenced in the outbound integrations.
  3. Make sure your event initiators have the roles they need to make requests in xMatters. Remember: for a user to make a request via the REST API, they must have the same permissions they would need to perform that action in the web user interface.
  4. For any request made by your outbound integration that needs to read or update xMatters data, make sure that your initiators have the correct permissions on other roles that those updates might require. For example, calling the GET people endpoint will require the correct role-on-role permissions for the user who initiated the form to be able to Use or View the relevant users.

Other helpful tips

In general, when building integrations, you should:

  • Choose the highest level of authentication for inbound integrations that the calling system supports. Again, URL Authentication is NOT recommended unless the calling system does not have the ability to provide authentication headers in the request. 
  • Remember that xMatters will treat any script request from the Integration Builder as being made by the same user that initiated the integration, and therefore restricted to that user's permissions.
  • Modify your integration scripts to handle the cases where the initiating user might not have the required permissions. This is especially important if, for example, you're retrieving a list of users and the returned results will be different if the initiating user doesn't have permission to view some of the people in your system.



If you do encounter any problems, or for technical assistance with these changes, contact xMatters Support.


Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk