Overview

This shall walk you through how you may obtain an authentication token in VIDIZMO using REST APIs. For more details, see: REST API Reference Guide - Authentication.


Acquire Access Token


User Credentials

Following is an example of how a bearer token can be obtained as well as the flow diagram: 



Request Method: POST


Request URL: /api/v1/user/authenticate

https://{{your-domain}}/api/v1/user/authenticate


Request Body: 
{ 
"emailAddress":"john.doe@gmail.com",
"password": "examplepassword"
}


Response Status Code:

200


Response Body:

"N2UCSNDDGI4NND5NMBZLV7ZBV2I3BZLUWQFXF6MGZKXTOCLHPH2SLPR2TMPM54M7CTG4DLFNE5KHSZ4LARTLQVRRCCRFAGVAG242M5RB3S5D4TEXKTSH4AHNMLTB3IF5IZYI4XSHRDDF2YFPLYAEMQL3Y3BKGZHCSDC2T2DQY64RC5Q3R5CQ" 


Client Secret

This method uses the user's email address and a Client Secret that is generated in the Authentication App created in the VIDIZMO portal. To learn more about Client Secret, see Authentications Methods in VIDIZMO


Request Method: POST


Request URL: /api/v1/user/authenticate

https://{{your-domain}}/api/v1/user/authenticate


Request Body: 
{ 
"emailAddress":"john.doe@gmail.com",
"clientSecret": "exampleclientsecret"
}


Response Status Code:

200


Response Body:

"N2UCSNDDGI4NND5NMBZLV7ZBV2I3BZLUWQFXF6MGZKXTOCLHPH2SLPR2TMPM54M7CTG4DLFNE5KHSZ4LARTLQVRRCCRFAGVAG242M5RB3S5D4TEXKTSH4AHNMLTB3IF5IZYI4XSHRDDF2YFPLYAEMQL3Y3BKGZHCSDC2T2DQY64RC5Q3R5CQ" 


Once a bearer token is obtained, then they can be passed in the header of the HTTP request to the VIDIZMO API for requesting further information. Further HTTP Requests can be made using the Authentication Token obtained. Here is how the authorization flow takes place. After VIDIZMO application receives the authentication token, it verifies whether the user to whom the token belongs is authorized to perform the action in the request. If the user is allowed to perform the action, then the call is successfully executed, otherwise an exception is thrown for unauthorized access.




When you try sending a HTTP Request with an invalid Access Token in the Request Header, the following is received: 


Response Status Code:

400


Response Body: 

{ 
"name": "InvalidAccessTokenException",
"incidentId": "167c0274-515e-4f16-a309-449c9573e9c6",
"exceptionDetails": []
}


What happens when token expires

A bearer token that has been generated can expire in two cases:

  1. When a user is made to log out via {{your-domain}}/api/v1/user/logout API.
  2. When a user is automatically logged out after the said duration of their token expiry (The default time for OAuth token to expire is 1 day).

 

VIDIZMO APIs will not be able to perform the action that is requested when a token has expired. 


Following is an example of a scenario when a bearer token has expired: 


Request Method: GET 


Request URL:  /api/v1/user/{emailAddress}

https://{{your-domain}}/api/v1/user/esther.fray%40gmail.com?userPartsToFetch=BasicInfo


Request Header: 

Authorization: Bearer <your-bearer-token>
Content-Type: application/json


Response Status Code

400


Response Body:  

{ 
"name": "ExpiredAccessTokenException",
"incidentId": "332d7070-78b3-4730-b76f-7a5adafeab31",
"exceptionDetails": []
}


Refresh Access Token

Once a token expires, you will have to refresh it in order to obtain a new valid token for authentication. Here is how you can do that:


Request Method:  POST


Request URL: /api/v1/user/refresh-access-token  

https://{{your-domain}}/api/v1/user/refresh-access-token/


Response Status Code:

200


Response Body:

<refreshed bearer token>