--- title: "DataEngine Authentication" slug: "dataengine-authentication" description: "Please provide the article content, including its headings and image alt text." updated: 2026-10-26T17:36:04Z published: 2026-10-26T17:36:04Z canonical: "docs.vastdata.com/dataengine-authentication" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.vastdata.com/llms.txt > Use this file to discover all available pages before exploring further. # DataEngine Authentication VAST DataEngine API requests require authentication. Authentication can be secured by: - [API tokens over HTTPS](/api-5-5/apidocs/dataengine-authentication#authentication-with-an-api-token) - [Basic Authentication](/api-5-5/apidocs/dataengine-authentication#basic-authentication), or - [JWT tokens over HTTPS](/api-5-5/apidocs/dataengine-authentication#using-json-web-tokens-for-authentication) ## 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](https://kb.vastdata.com/api-5-5/apidocs/cluster-api-introduction) 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 ``` ## 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 () in an authentication header with the following format: ``` Authorization: Bearer ``` 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/](/api-5-5/apidocs/dataengine-authentication#obtain-json-web-tokens) 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 ``` ### 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](/api-5-5/apidocs/dataengine-authentication#refresh-jwt-tokens). 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 ```