The VNTANA Admin API makes use of temporary tokens for all endpoints after authentication. All endpoints in the Admin API can be found here, while the endpoints available in the VNTANA Public API can be found here.
This guide is intended to clear up any confusion with terminology used in the guides on the VNTANA API. All endpoints after the login endpoint will pass a Request Header parameter called x-auth-token. However, this token will change 1 or 2 times in the full authentication process, depending on your user access level (view this guide to see how to check user access levels).
The main steps involved in authentication are:
- Authentication with Authentication Key or email / password:
- Does not pass an x-auth-token in the Request Headers.
- Returns an x-auth-token in the Response Headers. This is always referred to as an x-auth-token both in VNTANA’s guides and the API Documentation. It is only used in the process of retrieving a list of Organizations and generating a Refresh Token for a selected Organization, passed to both endpoints in the Request Headers as x-auth-token.
- Generating an Organization Specific Refresh Token.123456Method: POSTEndpoint: /v1/auth/refresh-tokenHeaders: {‘x-auth-token’ : ‘Bearer ‘ + x_auth_token,‘organizationUuid’ : ‘string’}
- Passes the x-auth-token retrieved in Step 1 in the Request Headers as x-auth-token.
- Returns an x-auth-token in the Response Headers. This is referred to as a Refresh Token in guides, but the parameter name to be passed is x-auth-token.
- The Refresh Token here is used for all future endpoints only if you have Organization Admin or Organization Owner level access, otherwise it’ll just be used to retrieve a list of Workspaces as well as to generate a Workspace specific Refresh Token.
- Generating a Workspace Specific Refresh Token.1234567Method: POSTEndpoint: /v1/auth/refresh-tokenHeaders: {‘x-auth-token’ : ‘Bearer ‘ + refreshToken,‘organizationUuid’ : ‘string’,‘clientUuid’ : ‘string’}
- Passes the Refresh Token from Step 2 in the Request Headers as the parameter x-auth-token.
- Returns an x-auth-token in the Response Headers. This is referred to as a Refresh Token in guides but the API documentation will show the parameter as x-auth-token still.
- This Refresh Token can only be generated if you do not have Organization Admin or Organization Owner level access, otherwise it’ll just return a BAD_CREDENTIALS error message.
- If this Refresh Token is generated, it’ll be used for all future endpoints, passed in the Request Headers as the parameter x-auth-token.
When a 403 Occurs
When using your refresh token on any of the authenticated endpoints in the VNTANA API, there are a couple of different errors and scenarios which may return a 403 error. When receiving one of these, look into these to determine whether there was an error with your request or a bigger issue which can be reported to our support at [email protected]
FORBIDDEN
If a 403 response returns this errror, it can mean a couple of things:
- Refresh Token has expired.
- No refresh token was sent.
- The refresh token sent doesn’t give access to the requested information or action (i.e. the refresh token gives access to a specific workspace and you try to retrieve info from another).
- The IP the request has come from does not exist on the list of whitelisted IP’s (if this setting is enabled).
BAD_CREDENTIALS
Some endpoints may return this error if the token has expired or is otherwise formatted incorrectly, but generally you should see the FORBIDDEN error.