Token Creation & Token Management

In this step as per OAuth protocol, the code received by the client in the authorization step will be exchanged to get the access_token which is used for accessing the Xoxoday storefront granted based on the scopes allowed by the user.

Access Token Generation

Request

The client server (As this request involves sensitive information i.e, client_secret) must make the following POST request to get the access_token.

curl -X POST {OAUTH_URL}/v1/oauth/token/company
-d '{
	"grant_type":"authorization_code",
	"code":"exxxx69660xxxxa6413c17d897xxxxx99",
	"redirect_uri":"{client_redirect_url}",
	"client_id":"{client_id}",
	"client_secret":"{client_secret}"
}

Response

After validation of these parameters by Xoxoday server the successful response will be :

{
    "access_token": "eyJ0b2tlbkNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk4MDQ1NTAxMzYsImV4cGlyZXNBdCI6IjIwMTktMDctMDZUMDc6MDI6MzAuMTM2WiIsInRva2VuX3R5cGUiOiJDT01QQU5ZIn0sImFfdCI6ImY3ZWM1MWMyYmE0ZGNmNzY2ZWE0ZDExMTI3ZjEzZjQzZjAwZmNhN2EifQ==",
    "token_type": "bearer",
    "expires_in": 2592000,
    "refresh_token": "064be187f42e9238122ef9d7a985c8800dff3752",
    "email":"[e-mail]" //This is the email of the user who allowed access
}

Parameters

Request

Body Parameters

Parameters	Description
token_type*	The token_type can be two values. They are company or user. If the request in the authorizationstep was for the company session creation then token_type value is the company or if the request in the step was for user session creation then token_type value is the user.
grant_type*	Although Oauth supports different grant_type values. The values supported by Xoxoday is authorization_code, refresh_token.
code*	Authorization codes expires in 5 mins after creation. This is the temporary code value which client has obtained after authorization.
client_id*	This is the client_id value that one receives upon registration inGetting Started step.
redirect_uri*	The URL must match what you have shared during the time of company registration.
client_secret*	This is the client_secret value that one receives upon registration in Getting Started step.

Response

Body Parameters

Parameters	Type	Description
access_token	Bearer	It can be used by client to access the API of xoxoday.
token_type	Bearer	It must be passed in the Authorization header.
expires_in		The duration (in seconds) for which access_token is valid. The default user session lasts for 15 days. The default company session lasts for 30 days.
refresh_token	Bearer	The value with which client can regenerate expired access_token. This refresh token for the user session lasts for 30 days and refresh token for company session lasts for 60 days.

Diagrammatic Representation for Authorization & Access Token generation.

Access Token generation from Refresh Token

Request

Upon Expiry the access token can be regenrated using the response token using the following request:

curl -X POST {OAUTH_URL}/v1/oauth/token/company
  -d '{
  "grant_type":"refresh_token",
  "refresh_token":"064be187f42e9238122ef9d7a985c8800dff3752",
  "client_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "client_secret":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Response

After validation of these parameters by Xoxoday server the successful response will be :

{
    "access_token": "eysdkhsdbjbdfsNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk4MDQ1NTAxMzYsImV4cGlyZXNBdCI6IjIwMTktMDctMDZUMDc6MDI6MzAuMTM2WiIsInRva2VuX3R5cGUiOiJDT01QQU5ZIn0sImFfdCI6ImY3ZWM1MWMyYmE0ZGNmNzY2ZWE0ZDExMTI3ZjEzZjQzZjAwZmNhsdjhfbsfdjblfs",
    "token_type": "bearer",
    "expires_in": 2592000,
    "refresh_token": "sdff064be187f42e9238122ef9d7a985c8800dff3752"
}

Parameters

Request

Body Parameters

Parameters	Description
grant_type*	Although Oauth supports different grant_type values. The values supported by Xoxoday is authorization_code, refresh_token.
client_id*	This is the client_id value that one receives upon registration inGetting Started step.
client_secret*	This is the client_secret value that one receives upon registration in Getting Started step.
refresh_token*	The value with which client can regenerate expired access_token. This refresh token for the user session lasts for 30 days and refresh token for company session lasts for 60 days.

Response

Body Parameters

Parameters	Type	Description
access_token	Bearer	It can be used by client to access the API of xoxoday.
token_type	Bearer	It must be passed in the Authorization header.
expires_in		The duration (in seconds) for which access_token is valid. The default user session lasts for 15 days. The default company session lasts for 30 days.
refresh_token	Bearer	The value with which client can regenerate expired access_token. This refresh token for the user session lasts for 30 days and refresh token for company session lasts for 60 days.

Note In the above response refresh_token is newly generated again. So the client-server must replace the old refresh token with this new refresh token.

While the expiry is 30 days for the access_token and 60 days for the refresh_token, Xoxoday recommends polling the Access Token generation from Refresh Token API on every 4xx error to ensure no downtime in case of a token invalidation before the 30-day expiry.

Diagrammatic Representation for Access Token regeneration.

Access Token Validation

Request

For verifying at any point in the app if the token is valid/not, call below endpoint.

curl -X GET {OAUTH_URL}/v1/oauth/token
-H 'Authorization: Bearer eyJ0b2tlbkNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk4MDQ1Nzg1ODIsImV4cGlyZXNBdCI6IjIwMTktMDYtMjFUMDc6MDI6NTguNTgyWiIsInRva2VuX3R5cGUiOiJ'

Response

200: Success

{
    "access_token": "eyJ0b2tlbkNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk4MDQ1Nzg1ODIsImV4cGlyZXNBdCI6IjIwMTktMDYtMjFUMDc6MDI6NTguNTgyWiIsInRva2VuX3R5cGUiOiJ",
    "token_type": "bearer",
    "expires_in": 1291911023
}

400: Failure

Token has expired.

{
    "error": "invalid_token",
    "error_description": "invalid/expired token"
}