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:
- 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.
- 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"
} -
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
-
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.
Comments
0 commentsArticle is closed for comments.