Using API Keys
Using API Keys
API Key Usage
Authentication to platform services is performed using bearer tokens. The bearer tokens are taken from API Key Secret that are generated on the API Key Management section of the platform.
This is an example of an API key that is generated and downloaded.
{
"appClientId": "7vcrn8enrtlrm5gnlqb24p5np2",
"appClientSecret": "vbh572suc403ec003m0so90uqqgr901j667c4hfi18rrbfcnu1",
"encodedKey": "asdfasdfasdfasdfasdfasdf"
}The key is composed of the appClientId, appClientSecret, and encodedKey elements. The encodedKey value is the value which must be used to obtain the access token for subsequent requests.
Redeeming an API Key for a Short Lived Token
In order to access the XTD APIs, the API key must be exchanged for an access token. The access token is used for accessing the specific API in question.
API Keys can be redeemed for short-lived Access Tokens using a POST to:
https://ssoapi-ng.platform.protectmyapp.com/v1/tokenThe request must include a body with the encoded API key (encodedKey value from the downloaded API key) in JSON format.
{
"apiKey": "<encodedKey from downloaded file>"
}The generated access tokens will have a 5-minute validity period. If making repeated calls to the XTD APIs, clients must keep track of the expiration of the token and make sure that, before it expires, another request for a new access token is made.
This API does check that the user’s organization is Active. If the user’s organization is inactive/disabled, then the request will be rejected with a 401 status code.
Example Token Retrieval Request and Response
POST /v1/token
{
"apiKey": "MmVlMmgwNTE2MjZsZnFzY2dsbGZjbXZxOWw6aG4zNXE3cjJzaG00OGI5NmtmYmIyc2xyZjllamRnMDlwbmpqOGZmM29iNDIwZDc4dmRm"
}would return a success response:
{
"token": "eyJraWQiOiI2SXJlMHZpVGd1OGVnSG9xc0trWjVnT3dpcmdIN1M1VlJwOER1VVllZ2tNPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiIyZWUyaDA1MTYyNmxmcXNjZ2xsZmNtdnE5bCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoicG9ydGFsLnBsYXRmb3JtLnZlcmltYXRyaXhkZXZjbG91ZC5uZXRcL1wveHRkOmFwaWtleTpydyBwb3J0YWwucGxhdGZvcm0udmVyaW1hdHJpeGRldmNsb3VkLm5ldFwvXC94dGQ6YXBwX2luc3RhbmNlX21nbXQgcG9ydGFsLnBsYXRmb3JtLnZlcmltYXRyaXhkZXZjbG91ZC5uZXRcL1wveHRkOmFwaWtleTpyIHBvcnRhbC5wbGF0Zm9ybS52ZXJpbWF0cml4ZGV2Y2xvdWQubmV0XC9cL3h0ZDptb25pdG9yaW5nIHBvcnRhbC5wbGF0Zm9ybS52ZXJpbWF0cml4ZGV2Y2xvdWQubmV0XC9cL3h0ZDphcGlrZXk6cndkIiwiYXV0aF90aW1lIjoxNjg2MzM3NDg5LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV9JdUJ5YzMzZzgiLCJleHAiOjE2ODYzMzc3ODksImlhdCI6MTY4NjMzNzQ4OSwidmVyc2lvbiI6MiwianRpIjoiMGMyMWEyMDMtODcyMS00OWZjLTlkZWYtYzhjN2U0NTdhMjJhIiwiY2xpZW50X2lkIjoiMmVlMmgwNTE2MjZsZnFzY2dsbGZjbXZxOWwifQ.HPq0311oahv_lCcx19ezRP7Deisyx_BO6sQIp4bg1xETSS-URMD971UiBh_rAbKfIEQLIS7X-zmO4Ce30kRu5AkMquUd44ACQfTHIeY3jSF3XK6zDYdtlri6vhK57cGMGtS-8CdnPAET8VFlaZtwY88kU1jRMYIY9j5rLaw_DKlfqMngyoIzP-1S7id2tLhgQwlYi0naynyNeCfmHib5f2Pu2x6oP-ri2eReNjClrYOjfL3SoIEi8-_nm4s922QuipN_2AuQ2WSCAuOVMRpYYKZdp2tXQ5B1UIahueXjNsXIjOy4au1oxkse7lzn5x6lV7uW-1tOYGqHBq1v6KbSiA",
"expirationTime": 300
}Using the Access Token
The generated access token can be used as a bearer token on requests towards the XTD APIs.
GET /v2/some/api
...
Authentication: Bearar <Token Value>
...