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.
A key step in any interaction with the VNTANA API is the retrieval of the Organization and Client / Folder you wish to work with. This is covered as part of the Authentication guide as in order to properly authenticate with a refresh token the Organization UUID and Client / Folder UUID are required, however this guide is intended to dive deeper into the endpoints in question and what information they will return.
Retrieve Organizations
Before being able to retrieve the list of Organizations, you must log in with either an email / password or authentication key. The following endpoint can be used to log in with an email / password.
The Request is structured as follows:
The Response is structured as follows:
Most users will only belong to one Organization, however the method to retrieve information assumes you may belong to more than one. The following endpoint will return a list of all Organizations that your account is associated with.
This passes the x-auth-token retrieved from logging in with either your email / password or authentication key. The response will contain a list of all Organizations associated with your account, in the following format.
The data returned for an Organization is used primarily for further authentication by generating a refresh token, but the information can also be used for a number of other API methods as well as embedding the viewer.
uuid: The unique ID of the Organization, used for generating a refresh token to access the rest of the API as well as passed in some other endpoints where the data is tied to the Organization and not a specific Client / Folder.
slug: A unique identifier of the workspace that is your Organization. This is generated based on the name of the Organization, which is not unique, and often times will be simply a hyphenated version of the name. This is utilized in the embed link and iFrame of a Product, as well as most Public API endpoints. Note: to manually retrieve this, simply find it in the URL of your Organization on the Platform:
https://platform.vntana.com/some-org-slug/some-client-slugname: The name of the Organization. This is not unique and thus only serves as a means by which you can verify the Organization if more than 1 is returned, though for that the slug would be better as that is unique.
role: Your role within the Organization. This can be used to determine whether authentication to a specific Client / Folder needs to be done as Organization Owners/Admins do not authenticate beyond the Organization.
imageBlobId: UUID of the Organizations ‘Profile’ picture, which is an optional feature.
created: The timestamp of when the Organization was created.
Retrieve Clients / Folders
Most use of the API will require a Client / Folder UUID as it is necessary to indicate the connection between certain entities and the Client / Folder they are contained in. In order to retrieve a list, however, you must first generate an Organization specific refresh token. You can see an example of this below.
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 return in the Response Headers as x-auth-token.
Once a valid refresh token has been generated, you can call the following endpoint to retrieve the list of Clients / Folders associated with your account.
This passes the refreshToken generated for the Organization you’ve selected in the headers and receives the following response when successful.
Like with the Organization response, the data returned for a Client / Folder can be utilized for a number of purposes.
uuid: The unique ID of the Client / Folder used for most API calls which involved entities that are specifically linked to the Client / Folder they are contained in.
slug: A unique identifier for the Client / Folder generated by the name of the Client / Folder when created. Usually just a hyphenated version of the name (except when the name isn’t unique), it is used in the embed links and iFrames as well as Public API endpoints. Note: To manually retrieve this simply look to the URL of the Client / Folder
https://platform.vntana.com/some-org-slug/some-client-slug.name: Simply the name you give to the Client / Folder, this is not a unique parameter but can be used to verify the Client / Folder you wish to work with from the list returned from this endpoint, though the slug would be a better option for this.
role: Your role in the Organization, though some might have Client / Folder level user access, it is still tied to the Organization. Having Client / Folder level access means only those Clients / Folders you’ve been added to will be returned by this endpoint.
imageBlobId: UUID of the ‘Profile’ picture of the Client / Folder.
created: Timestamp indicating when the Client / Folder was created.
In most cases, the UUID of the Organization or Client / Folder is the only information needed from these endpoints, however these values are integral with most VNTANA Admin API interactions, most notably with authentication and as such both should always be a part of any process involving the VNTANA API.
Additional information on topics mentioned in this guide can be found in the following guides: Authentication, Auth Token Usage, and iFrames. Another means by which Organization and Client / Folder information can be obtained is via Webhooks for specific use cases including when a Client / Folder is created.
You can test these using the Postman collection for User Authentication, provided below and in the Authentication guide. 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.