Authentication

VAST DataEngine API requests require authentication.

Authentication can be secured by:

Authentication with an API Token

Obtaining an API Token

Tokens can be created by VMS manager users, which may be either cluster admin or tenant admin type users. Creating API tokens requires create permission for the Security VMS RBAC realm. Tenant admin users can create tokens only for users on the same tenant.

For information about creating and otherwise managing tokens, see the VMS REST API documentation.

Authenticating a Request with an API Token

To authenticate each request, send a current valid API token in an Authorization header with the following format:

Authorization: Api-Token <token>

Basic Authentication

When authenticating a request with basic authentication, you need to:

Supply your user name and password. This may be the user name of a tenant admin user (a type of VMS user intended for administrating a specific tenant of a cluster) or an application user (a type of user intended for accessing VAST DataEngine on a specific tenant of a cluster.
Authenticate to the specific tenant hosting the DataEngine you are trying to access. To do this, add the X-Tenant-Name: <tenant_name> header to your request where <tenant_name> is the name of the tenant.

Using JSON Web Tokens for Authentication

The VAST DataEngine API supports authentication secured by JSON Web Tokens (JWTs) over HTTPS, like the VMS API.

To establish authentication, your script calls an endpoint via HTTPS to generate a pair of tokens. The request supplies a VMS user name and password in the request body. The response returns a pair of tokens: an access token and a refresh token.

The access token is a digitally encoded signature used to authenticate requests and authorize access to the requested endpoint. It is designed to have a minimal lifetime, to ensure minimum time for the requesting user's identity to be exploited. The refresh token must have a longer lifetime than the access token. It can be used to request new tokens. The new access token can then be used to authenticate further requests.

Authenticating Requests with JWT Access Tokens

To authenticate a request with a JWT access token, send a current valid access token (<token>) in an authentication header with the following format:

Authorization: Bearer <token>

For example, the following request to the /dashboard/status endpoint is authenticated with an access token yJ0eXAiOiJKV1Q...:

curl 'https://192.0.2.1/api/dashboard/status/' \
  -H 'authority: 192.0.2.1' \
  -H 'pragma: no-cache' \
  -H 'cache-control: no-cache' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjI0ODg2NTA5LCJqdGkiOiI0ODZiZjIwNDVkMjY0ODllODhiZmNiYzhkZTM0Yzk5MCIsInVzZXJfaWQiOjJ9.OPhNseLkVr7uY3Rv5FZ5T4GsOj8bfW4ai-OOPSjIb6Y' \
  -H 'content-type: application/json' \
  -H 'referer: https://192.0.2.1/' \
  --compressed \
  --insecure

Generating Tokens

To generate the initial access token, make a POST request to the /api/token/ endpoint.

You need to pass a VMS user name and password as the required body parameters.

The response returns two tokens:

The access token to use for authentication on protected API endpoints.
The refresh token, which you can use to obtain a new access token and refresh token.

cURL Example

Using cURL, with ABC resolves to your cluster's VMS VIP, your user name is user and the password for user is XXXXYX:

curl 'https://192.0.2.1/api/token/' \
  -H 'authority: 192.0.2.1' \
  -H 'pragma: no-cache' \
  -H 'cache-control: no-cache' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'content-type: application/json' \
  -H 'origin: https://192.0.2.1' \
  -H 'referer: https://192.0.2.1/' \
  -H 'accept-language: en-US,en;q=0.9,he;q=0.8' \
  --data-binary '{"username":"user","password":"XXXXYX"}' \
  --compressed \
  --insecure

Using the Token in a Request

To authenticate each request, send a current access token in an authentication header in the following format:

Authorization: Bearer <token>

Keeping Tokens Valid

If the access token expires while the refresh token is still valid, the refresh token can be used to generate new tokens without supplying the VMS user credentials. If the refresh token expires, requests require re-authentication with the VMS user credentials.

In order to avoid the need to re-authenticate with a VMS user, your script needs to refresh the tokens periodically, at least once in the lifespan of each refresh token. Since the access token has a shorter lifespan, refresh is also needed more frequently in order to continue making requests.

One suggestion is to send a refresh request on receiving a 401 failed request error and retrying the request with the fresh returned access token.

The token lifespans are configurable with the following defaults:

The access token has a default lifespan of 1 h.
The refresh token has a default lifespan of 24 h

Refreshing Tokens

To refresh the tokens, make a POST request to api/token/refresh. Pass the last refresh token returned by the last refresh request as data.

The response is a new access and a new refresh token. Save them and use the new access token to access API endpoints, and the new refresh token to refresh tokens again.

cURL example:

curl 'https://192.0.2.1/api/token/refresh/' \
  -H 'authority: 192.0.2.1' \
  -H 'pragma: no-cache' \
  -H 'cache-control: no-cache' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'content-type: application/json' \
  -H 'origin: https://192.0.2.1' \
  -H 'referer: https://192.0.2.1/' \
  -H 'accept-language: en-US,en;q=0.9,he;q=0.8' \
  --data-binary ‘{“refresh”:“eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTYyNDk2OTMwOSwianRpIjoiZGVhNzlkOTI1ZjBmNDQyNTg4MDgyMTg4ZDZlZjY2OTUiLCJ1c2VyX2lkIjoyfQ.gTOhjyfGsN7ebBgEiPa94_rjESUFGCEvFMObAkisyDI”}’ \
  --compressed \
  --insecure