Manage API key credentials

The API Keys tab in a user's profile (or the profile of a user you supervise) allows you to manage the API key credentials that are associated with that user. You can use API key credentials to authenticate requests to the REST API, trigger flows in Flow Designer, and initiate any integration that is configured to support API authentication using a unique, user-assigned API key as the username, and a randomly-generated secret as the password. (API key credentials cannot trigger flows that are set to require Basic authentication; choose the API Key Authentication method, or set the trigger to allow all methods.)

Each user in the system has a unique API key, but you can create multiple sets of credentials, each with a unique secret. This allows multiple systems to authenticate using the same user account, while controlling each system's access separately and without needing to store your xMatters user ID and password in multiple places.

A request using API key credentials has the same permissions and access to data in xMatters as the associated user, but the key and secret cannot be used to log into the web user interface, and the credentials will continue to work even if the associated user changes their password. However, API key credentials will stop working if the user is deleted from xMatters.

You can create multiple API key credentials for a single user and manage the list on the user's Profile page. This means you can still set up different credentials on different systems (however many you have sending signals into xMatters) without requiring a separate user license for each one.

To create API key credentials:
  1. Do one of the following:
    1. To create API key credentials for your own account, click your username at the top-right corner of the screen, and then click Profile.
    2. To create API key credentials for a user you supervise, locate them on the Users page and click their name to open their profile.
  2. On the user profile, click the More Actions drop-down menu and select Manage API Keys.
  3. In the Manage API Keys dialog box, click Create API Key Credential.
  4. In the Create API Key Credential dialog box, enter a Name and Description for the credential.
    1. Be as descriptive as you need to be to distinguish this credential from any others you may need to create. A good approach is to name the credential after the system that the credentials are for, and add a brief description about the intended usage.
  5. Click Create to add the credential and generate the secret.

This is the only time that the secret will be displayed - be sure to copy it immediately to the calling system or to a secure location. As soon as you close this dialog box, you cannot view the secret again. If you forget or lose the secret, you'll need to generate a new one, which will also cause the existing secret to stop working.

  1. Click Close to return to the credentials list.

You can regenerate the secret for an API key credential at any time. If you regenerate the secret, you must update the calling system to use the new secret. You do not need to regenerate a new secret or update the calling system if the authenticating user's password changes in xMatters.

To regenerate a secret:
  1. On the user profile, click the More Actions drop-down menu and select Manage API Keys.
  2. In the Manage API Keys dialog box, click the name of the credential you want to regenerate the secret for.
  3. In the Edit API Key Credential dialog box, click Regenerate Secret.

Make sure you copy the secret to the calling system or other secure location immediately. Once you close the dialog box, the secret will not be displayed again.

If a set of credentials is no longer in use, or if you want to remove access from a system configured with API key credentials without modifying the calling system, you can revoke or remove the credentials from the user's list.

To revoke an API key credential:
  1. On the user profile, click the More Actions drop-down menu and select Manage API Keys.
  2. In the Manage API Keys dialog box, go to the Status column and click the toggle for the credential you want to revoke.
  3. Click Revoke in the pop-up to confirm your selection.

The status of the API key is changed to "Revoked" and any future requests submitted using the revoked credential will be rejected.

To remove and invalidate API key credentials: 
  1. On the user profile, click the More Actions drop-down menu and select Manage API Keys.
  2. In the Manage API Keys dialog box, locate the credential you want to remove then click the trash can icon on the right side of its row.
  3. In the Delete API Key Credentials pop-up, click Delete.

Any future requests submitted using the deleted credentials will be rejected. Deleting a user also removes all of their API key credentials.