Authentication and Permissions (GIG part 4)

NOTE: This article is outdated and will be fed to the Balrog. Instead, just create a user and give them the REST Web Services User role.


So you want to build an integration. You want to move information from point A to point B and point B is xMatters. Except xMatters has the latest in security protocols.


Fortunately, there is a solution! Authentication and permissions in xMatters for integrations actually work the same way they do for normal users!

However, first we have to add a new REST Web Service user role to get just the right level of permissions. In the future, this will be available out of the box, but for now we'll step through the process of creating this role. Note: To edit steps in the xMatters On-Demand environment, contact the friendly folks at Customer Support, or open a ticket with support and they will help you get this created. 

We want a role that allows the integrations user to be able to create events, terminate events, retrieve events and interact with some of the properties of communication plan. But we don't want this user to be able to login to the user interface and make updates to users or groups or administrative settings. (This can help those security folks rest a bit easier, especially if the external system where the username and password are stored is available in plain text, as is still the case with some systems.)

A "role" is actually composed of several subdivisions. At the top are the "roles" that are granted to users. A role is composed of zero or more functions. (I say zero or more because a role can just be part of a matrix on what it can do to other roles. I won't go into details on this part here, but check out the docs or post a message in the community and we'll get you the info you need.) And a function is composed of one or more permissions. Like so:




Ok, theory out of the way, let's get to work.

To begin, log in to xMatters (as a Company Administrator) and navigate to the Admin tab > Permissions > Functions. Then click Add New.

Enter the name of the function and a description of what it is going to do, and then click Save. The text I've used below is "REST Web Service User" and "Limited user with the ability to POST, GET and PUT events." 

xMatters then displays the Permissions page, which really looks a bit daunting but you can hover over each permission in the list to see a short description of what it does.

Luckily, I've already done the leg work to figure out what we need. Select each of the following permissions and move them to the Selected Permissions side. (Check out the REST API docs here for more details about what these actions mean.)

Action Permission  Description
PUT properties  ability.act.EditProperty Allows for updating the properties of a communication plan.
PUT events ability.act.EventAdministration Terminate events
POST events Create events
GET notifications view.menuitem.NotificationReport Get details of what transpired in an event. (who responded what how and when)
GET events view.screen.EventActivityReport Query for events based on properties. 
GET groups view.menuitem.Groups Query for groups

Click Save, and you've just created a REST Web Service function with the necessary properties. The next step is to create the role that will use this function.

On the Admin tab click Roles and click Add New. Again, give it a descriptive name and a short description. I've used "REST Web Services User" and "All necessary permissions for using the REST web services", respectively. 

Now scroll down to the second matrix where it says "PERMISSIONS OTHER ROLES HAVE" IN ALL CAPS! This section details what other roles can do with this role. In this case, let's grant the "Company Supervisor" and "Developer" roles the ability to Assign this Role. Then hit Save. 

Now, we get to apply our newly created function to this role. Select "REST Web Services" function and move it to the Selected Functions side, and then hit Save. 

Almost there! The final part is to create the actual user and grant them our shiny new role.

Navigate over to the Users tab and click the Add New user button ()  at the top. Note that while I'm going to call my user "my rest user", please, please, please use something more descriptive. Trust me, this will really help down the line when you are trying to figure out what integration is sending you messages at 2am. For example, in our integrations, we name the user after the management system: ServiceNow, Splunk, Nagios, etc. 


Now we make sure to grant our new role to the user by moving the REST Web Service User role over to the Selected Roles. 

The last step in all this is to set the authentication part... the Web Login ID and password. This is where we define the password for our user. Enter a hardy password in the boxes and click Save. (Note that I do not recommend clicking "Force Password Expiry" as the user won't be able to login to change it!)

That's it! Stay tuned for the next installment when we put this user to work!

Happy Integrating!

P.S. Note that all of this applies to REST web service actions and NOT SOAP web service actions. Later in the series when we go into data integrations we'll go over authentication and permissions for SOAP users, but for now check out the docs.


 Click here for the next installment of the GIG!


Have more questions? Submit a request


  • 0
    Scott McNall

    For GET groups, the permission is view.menuitem.Groups

  • 0
    Travis DePuy

    Thanks! I'll update the table. 

Please sign in to leave a comment.
Powered by Zendesk