Using OAuth with xMatters

Question 

How do I use OAuth with my API requests? Do I need a client secret?

Environment

All versions of xMatters On-Demand

Answer

xMatters uses OAuth 2.0 and as such you simply need to provide a Bearer authorization header in the API request. To generate that you need to send an API request to get the token:

1.  Obtain the client ID for your xMatters instance. You can locate the client ID for your company on the OAuth page of the Workflows tab.
   
2. Obtain an access token using the /oauth2/token endpoint. In CURL this would look like:
   
   curl --request POST --header "Content-Type: application/x-www-form-urlencoded" --data
   'grant_type%3Dpassword%26client_id%3D7469ebe0-4dff-4a1b-84fe-0d1b3baf9dcf%26username%3Dusername%26password%3Dpassword%0A%20'
   
   Where the second username and password parameters represent the credentials of the user account you want to authenticate with and generate a token for.
   
   You would get back something like this as a response:
   {
   "access_token":"eyJhbGciOiJSUzI1NiJ9.eyJwIjoiLy8vL3ovLy8vLy8vLy8vLy8vLy8vLy8vLy8vLytmLy8vLy8vLy9QLy8vLy8vLy8vQi83Ly8vLy8vLy8vLy8vLy8vLy8vLy8vLy8vL0R3PT0iLCJhdWQiOlsiaWJhdXRvMS5iZXNwaW4uc2hhcmVkLWRldi54bWF0dGVycy5jb20iXSwic3ViIjoic2FuZHJhIiwiYXpwIjoiNzQ2OWViZTAtNGRmZi00YTFiLTg0ZmUtMGQxYjNiYWY5ZGNmIiwiaXNzIjoieG1hdHRlcnMiLCJzYmkiOjUxNDY0MiwiZXhwIjoxNDc1ODYxMzQwLCJpYXQiOjE0NzU4NjA0NDAsImFpZCI6MjAwMDIyLCJqdGkiOiI1YTNkNWY3MC0yYmZiLTQ1YTUtOWVhOC1mZDY5ZDUzMDU5ZGYifQ.B0_fslYEiq7mNiTDR7QUg1n3aFmQtlsXanzLZi5FGXJooqZo-OqgpkfSekkNTXwED7kTPkg8Yw3TgyO8V5UIGvstpuibvuu130z0hRCQU0UOMN8O1f9xlpLl3Z3ZqOhGjIQfS4WJKyKI7lA98KnFJ7z9zNN98X59AgBA3PFdf7OSsHDPpBHZakxolRfa85gFxONzpZSVCxPaIN7SE179a-VYbZPvIVieXC4BSUi7S5zVhgCJFynsTfmUe62SWWqrvjq09rEi1I-MhsQNnASL1xuXHyiJrBBUoiM8rid9q9LKU8eB6aZmAET72-URDk3ym1xMfGgpDFO8dnKpersnLA",
   "token_type":"bearer",
   "refresh_token":"4a90179e-12e8-4965-bc0c-66c0f6b70458",
   "expires_in":588,
   "jti":"5a3d5f70-2bfb-45a5-9ea8-fd69d53059df"
   }
3. Authorize a request using the OAuth token by including the “Authorization: Bearer” header in each request and set its value to a valid access token.

   EXAMPLE AUTHENTICATION HEADER:
   Authorization: Bearer eyJhbGciOiJ ... BTfs9sivw4QYk5xCJoaex7p8kf6KUg

4. If the access token expires, you can obtain a new one by providing the client ID and a refresh token with the same /oauth2/token endpoint.
   
   The CURL request looks like this:

   curl --request POST --data
   'grant_type=refresh_token&client_id=7469ebe0-4dff-4a1b-84fe-0d1b3baf9dcf&refresh_token=2c0a3418-2159-404a-8b04-88b5cf0a2b62'
   "https://acmeco.xmatters.com/api/xm/1/oauth2/token"
   
   And the response looks like this:

   {
   "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJwIjoiLy8vL3ovLy8vLy8vLy8vLy8vLy8vLy8vLy8vLytmLy8vLy8vLy9QLy8vLy8vLy8vQi83Ly8vLy8vLy8vLy8vLy8vLy8vLy8vLy8vL0R3PT0iLCJhdWQiOlsiaWJhdXRvMS5iZXNwaW4uc2hhcmVkLWRldi54bWF0dGVycy5jb20iXSwic3ViIjoiYWRtaW4iLCJhenAiOiI3NDY5ZWJlMC00ZGZmLTRhMWItODRmZS0wZDFiM2JhZjlkY2YiLCJpc3MiOiJ4bWF0dGVycyIsInNiaSI6NTE0NTE1LCJleHAiOjE0NzYyMTYzMzgsImlhdCI6MTQ3NjIxNTQzOCwiYWlkIjoyMDAwMjIsImp0aSI6IjUyYzc5NDExLTNkMWUtNDUyZS1iOGM5LTJmNTAzYTc3NzFmOCJ9.TZPluCuR8RAXvtxPjO8E4FyFttLJNKD5KgkchZAKbYv5SpfpovBekJXTPnLIEVQ8NE88-rS0g6NnwRte8aDGN_hb5Y9-cNF1V5K-g9fuAXoYT1CIPMEDf-LFRGHeSkoo6yYkzQEloclOi6GFprLtm1XvKoPSK5hB8QT5uU6TJVc2UMjM7QTO7j3Tya8h0KByU_CE0wZxic45qrtRpyE__PIE_JqQJ8bwOuFUE3LC0Wfzcf0zIHrBIkv_jV2Wi_ktBwJwEmoRCMeDXvPozW2iFUC_5KhYWjO9eCVEU8u2tWqdwfQ7muPZnsIFTiH1rAvL_8sxaM3ZSke1AulwzadSYg",
   "token_type": "bearer",
   "refresh_token": "2b0a3418-2159-4042-8b04-38b5cf0a2b62",
   "expires_in": 899,
   "jti": "52c79411-3d1e-452e-b8c9-2f503a7771f8"
   }

For more documentation on the usage of oAuth you can check our documentation or our API definitions.