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 Workspace.
A key step in any interaction with the VNTANA API is the retrieval of the Organization and Workspace 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 Workspace 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 Workspace.
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 an Asset, 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 Workspace 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 Workspaces
Most use of the API will require a Workspace UUID as it is necessary to indicate the connection between certain entities and the Workspace 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 Workspace 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 Workspace can be utilized for a number of purposes.
uuid: The unique ID of the Workspace used for most API calls which involved entities that are specifically linked to the Workspace they are contained in.
slug: A unique identifier for the Workspace generated by the name given 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 Workspace
https://platform.vntana.com/some-org-slug/some-client-slug.name: Simply the name you give to the Workspace, this is not a unique parameter but can be used to verify the Workspace you wish to work with from the list returned from this endpoint, though the slug would be a better option for this. Note: the name of a Workspace can be changed, but the slug will always remain what was initially assigned at creation.
role: Your role in the Organization, though some might have Workspace level user access, it is still tied to the Organization. Having Workspace level access means only those Workspaces you’ve been added to will be returned by this endpoint.
imageBlobId: UUID of the ‘Profile’ picture of the Workspace.
created: Timestamp indicating when the Workspace was created.
In most cases, the UUID of the Organization or Workspace 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 Workspace information can be obtained is via Webhooks for specific use cases including when a Workspace 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.