Resources

API – Authentication

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 hereNote: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the workspaces one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Workspace

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:

1
2
3
4
5
6
7
{
“success”: true,
“errors”: [],
“response”: {
“email”: “some.email@example.com”
}
}

2. Get Organization UUID – step can be skipped if this UUID is stored locally.

The Request is structured as follows:

1
2
3
Method: GET
Endpoint: /v1/organizations
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token}

The Response is structured as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “string”,
“slug”: “some-org-slug”,
“name”: “Some Org,
“role”: “ORGANIZATION_ADMIN”,
“imageBlobId”: “string”,
“created”: “2020-01-31T19:17:23.972”
}
]
}
}

3. Generate Organization specific Refresh Token using x-auth-token from Step 1.

The Request structure is as follows:

1
2
3
4
5
6
Method: POST
Endpoint: /v1/auth/refresh-token
Headers: {
‘x-auth-token’ : ‘Bearer ‘ + x_auth_token,
‘organizationUuid’ : ‘string’
}

The x-auth-token is the one returned in the Response of Step 1.

The Response structure is as follows:

1
2
3
4
5
6
7
{
“success”: true,
“errors”: [],
“response”: {
“email”: “some.email@example.com”
}
}

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:

1
2
3
Method: GET
Endpoint: /v1/clients/client-organizations
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken}

The Response structure is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “string”,
“slug”: “some-client-slug”,
“name”: “Some Client,
“role”: “ORGANIZATION_ADMIN”,
“imageBlobId”: “string”,
“created”: “2020-01-31T19:17:23.972”
}
]
}
}

5. Generate Workspace 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:

1
2
3
4
5
6
7
Method: POST
Endpoint: /v1/auth/refresh-token
Headers: {
‘x-auth-token’ : ‘Bearer ‘ + refreshToken,
‘organizationUuid’ : ‘string’,
‘clientUuid’ : ‘string’
}

The refreshToken here is the x-auth-token obtained from Step 3.

The Response structure is as follows:

1
2
3
4
5
6
7
{
“success”: true,
“errors”: [],
“response”: {
“email”: “some.email@example.com”
}
}

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.

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

Tap the magnifying glass to the left of your screen to search our resources.