Authentication Process

Authentication Process #

Requests to the API are secured via a JWT access token. This token needs to be generated using the OAuth v2 Authorization Code grant flow.

The image below provides an outline of the process involved in generating the required tokens and keeping them alive:

Support Login

Please refer to the links below for detailed technical information and code examples of the Authorization Code grant flow:

To progress with the steps below, you will need:

  • The Request_URL, Client_ID & Client_Secret (these will be provided to you when you request API access)
  • A user login for the ~.Dimensions.~ Reseller Portal to approve the authorization.
Color Wand tip
If you are having problems at any stage and require assistance, please contact us at [email protected] or call us on (+1) 480 207 7920.

1. Request Authorization #

The first step is to request authorization - https://login.xarios.cloud/connect/authorize.
Construct a URL containing the items below:

  • Client_Id: The client_id is provided when first requesting API access.
  • Response_Type: Use "code".
  • State: Provide a state which can be used to identify the redirect
  • Redirect_URI: This sets the redirect URL that is used after a token has been issued. The default is http://127.0.0.1:8000.
  • Scope: This is the list of scopes that need to be provided when requesting a token. This should be set to "openid offline_access onboarding".

Once the authorization request has been made, you will be presented with the login screen for the ~.Dimensions.~ Reseller Portal.

The redirect URL should now have been passed an 'Auth Code' which can be used in step 2.

Example Request

https://login.xarios.cloud/connect/authorize?client_id=123456&response_type=code&state=5ca75bd30&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&scope=open%20id%20offline_access%20onboarding

2. Request Access & Refresh Tokens #

The 'Auth Code' now needs to be exchanged for access and refresh tokens - https://login.xarios.cloud/connect/token.

  • Access Token, used to access the API features and perform onboarding requests.
  • Refresh Token, used to generate ongoing access tokens

This can be done by making a POST request to the authorization server containing for following items:

  • Code: The auth code collected in step 1.
  • Grant_Type: Set to authorization_code. (As per the https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type spec).
  • Client_Id: The client_id is provided when first requesting API access.
  • Client_Secret: The client_secret is provided when first requesting API access.
  • Redirect_URI: This sets the redirect URL that is used after a token has been issued. The default is http://127.0.0.1:8000.

Example Request 

POST https://login.xarios.cloud/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: xx
code=98765&grant_type=code&client_id=123456&client_secret=987654321&redirect_uri=https%3A%2f%2fexample.com%2fauth

The auth server validates the request and responds with an access token and refresh token:

Example Response 

{  
  "access_token": "AYjcyMzY3ZDhiNmJkNTY",  
  "refresh_token": "RjY2NjM5NzA2OWJjuE7c",  
  "token_type": "bearer",  
  "expires": 5400  
}

At this stage you should be in possession of both access and refresh tokens. The access token can be used to perform API onboarding requests as required.

For information on using the API, please refer to the API Reference.

3. Refreshing the Access Token #

The lifetime of the access token is set to 1 hour. After this time, a new access token will need to be generated using the refresh token.

To avoid requiring any user interaction to generate a new access token, a refresh token is used. The refresh token can be used to request a new access token when the original one has expired.

This can be done by making a POST request to the authorization server containing for following items (this is the same as step 2 but uses the Refresh Token instead of the Auth Code):

  • Refresh_Token: The stored refresh_token collection in step 2.
  • Grant_Type: Use "refresh_token".
  • Client_Id: The client_id is provided when first requesting API access.
  • Client_Secret: The client_secret is provided when first requesting API access.

Example Request

POST https://login.xarios.cloud/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: xx
refresh_token=RjY2NjM5NzA2OWJjuE7c&grant_type=refresh_token&client_id=123456&client_secret=987654321
Information Circle info
Adding the offline_access to the scope when requesting authorization in step 1 process will cause a refresh token to be generated along with the initial access token.

Hand Left warning
Refresh tokens will expire if not used for a period of 90 days. The expiry time will keep being reset to 90 day every time the refresh token is used.

Revoking Tokens #

If the token becomes compromised then the access token cannot be revoked but the refresh token can. Contact support immediately if this happens or disable the REST API through the Reseller Portal.