API Base URL: https://api-platform.vntana.com
For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.
Authentication with the VNTANA Platform can be accomplished using an Authentication Key or a valid email / password. Which method to use is dependent on your preference as either can be stored locally and implemented in an automated manner, though for this we would recommend using an Authentication Key.
Authentication with Email and Password
This form of authentication works as expected, simply passing a valid VNTANA Platform user email and associated password to the following Endpoint will return an x-auth-token:
Method: POST
Endpoint: /v1/auth/login
Request Body: { 'email' : 'someemail@email.com', 'password' : 'somePassword' }
Authentication with Authentication Key
An Authentication Key (otherwise known as a personal-access-token in the API) can be generated on the VNTANA Platform and used to authenticate in place of an email / password. See here to learn how to generate this key. Use the following Endpoint to retrieve an x-auth-token:
Method: POST
Endpoint: /v1/auth/login/token
Request Body: { 'personal-access-token' : 'somePersonalAccessToken' }
For both key and email / password authentication, the x-auth-token is returned in the Response Headers, and the subsequent process involves the same steps.
1. Login with Authentication Key or email / password – retrieve x-auth-token.
The Response of a successful login is structured as follows:
2. Get Organization UUID – step can be skipped if this UUID is stored locally.
The Request is structured as follows:
The Response is structured as follows:
3. Generate Organization specific Refresh Token using x-auth-token from Step 1.
The Request structure is as follows:
The x-auth-token is the one returned in the Response of Step 1.
The Response structure is as follows:
The Refresh Token will be returned in the Response Headers as x-auth-token.
4. Get Client / Folder UUID – step can be skipped if UUID is stored locally.
The Request structure is as follows:
The Response structure is as follows:
5. Generate Client / Folder specific Refresh Token.
- If you have Organization Admin or Owner level access, this must be skipped. To learn how to check your access level see this guide.
The Request structure is as follows:
The refreshToken here is the x-auth-token obtained from Step 3.
The Response structure is as follows:
The Refresh Token will be returned in the Response Headers as x-auth-token
To see a more detailed explanation of the x-auth-token / Refresh Tokens and when each is used, see this guide here.
Once a Refresh Token has been successfully generated, this token can then be passed to any future Endpoints as a Request Header parameter called x-auth-token.
You can download the below Postman collection to test out the Authentication endpoints discussed. As mentioned, this general process will be required at least once every session with the API (the Refresh Token will persist so you can make multiple calls with it). To use the Postman collection, simply set the global variables you wish to use, or manually edit the individual endpoints with the necessary information. You can view a summary on using Postman collections here for more information, but generally the collections are set up to be able to run as one chain of endpoints (you will have to select which method of authentication, key or email / password) though you can run them individually by activating the headers that are deactivated and filling in any necessary request body parameters.