REST API Version: 1.0.0
REST APIs
Authentication & Authorization
All OnCommand Connection APIs have two layers for Authentication and Authorization. These are enforced through the use of two HTTP headers, namely, Authorization and Subscription Key.
Authorization header
OnCommand Connection APIs are protected using OAuth 2.0. An API caller would need to provide Authorization header with Bearer Token in order to call the APIs on the platform. Bearer Token is generated by calling the Token API as shown in the sample below. Token API requires Client ID and Secret as inputs. These are created on registering client application in the Profile section of Developer Portal. The Bearer token is a JSON Web Token (JWT) which is used by API Gateway for request validation.
Token API Sample
Example
The following HTTP POST requests an access token. The client_id identifies the application that requests the access token.
Method : POST
URL : /authorization/oauth2/token HTTP/1.1
Host : api.oncommandconnection.com
Headers:
Content-Type : application/x-www-form-urlencoded
SubscriptionKey: b3898388378738787387387
Body:
{ "client_id": "string", "client_secret": "string", "grant_type"="client_credentials" }
URL : /authorization/oauth2/token HTTP/1.1
Host : api.oncommandconnection.com
Headers:
Content-Type : application/x-www-form-urlencoded
SubscriptionKey: b3898388378738787387387
Body:
{ "client_id": "string", "client_secret": "string", "grant_type"="client_credentials" }
The successful response will be as follows
{ "token_type": "Bearer", "expires_in": 3600, "ext_expires_in": 3600, "expires_on": 1558351310, "not_before": 1558347410, "access_token": "eyJhbG...MINA" }
Access Tokens are short-lived and must be requested again after they expire to continue accessing resources. You can submit another POST request to the token endpointYour application needs to expect and handle errors returned by the token issuance endpoint correctly. When you receive a response with a refresh token error, discard the current refresh token and request a new access token.
Subscription Key Header
Subscription key is generated on subscribing to a Product plan in the Products section. Subscription key is used validate if a particular user has the access to call particular API or not. Subscription key mapped to a product can be used for only those APIs which are grouped under a product plans. Visit the Products page to get details on Product plans and APIs in each.
Index
