--- title: "Getting Started" slug: "cluster-api-getting-started" description: "VMS REST API guide: master HTTPS requests, authentication tokens, pagination, query parameters, permissions, error codes, and mTLS client certificates." updated: 2026-10-26T17:24:46Z published: 2026-10-26T17:24:46Z canonical: "docs.vastdata.com/cluster-api-getting-started" --- > ## 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. # Getting Started ## Making API Requests The VMS REST API documentation describes many types of resources and operations you can call. To call an operation: - Send a request to an endpoint formed as: ``` https://VMS_VIP/api/VERSION/OBJECT/ ``` - Specify one of several methods: Most endpoints can be accessed by several methods. For example, you can send a POST request to the `/views/` endpoint to create a new view, a DELETE request to the same endpoint to delete a view, and so on. - POST to create a resource of a given type, - PATCH to change one or more properties of a given resource, - DELETE to delete a specified resource, or - GET to return information about one or more resources. The endpoint URL includes: - *VMS_VIP*, an IP specific to the cluster for accessing VMS. It's provided at cluster installation, and it's the same IP that you use to browse to the VAST Web UI. - *VERSION*, the VMS API Version. This is optional, but important. If not specified, the endpoint is requested from the *oldest* available version of the API (not the latest!). When usage changes from one version to the next, the older version number enables you to retain the functionality of the former version. If the cluster does not support the specified version, an error is returned. The following expressions are supported for *VERSION*: | | | | --- | --- | | `v1` | Requests the last version of the API endpoint that was introduced up to VAST Cluster release 4.3, even if the cluster is running a later version. | | `v2` | Specifying v2 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 4.4 and is supported on the cluster. | | `v3` | Specifying v3 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 4.7 and is supported on the cluster. | | `v4` | Specifying v4 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.0 and is supported on the cluster. | | `v5` | Specifying v5 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.1 and is supported on the cluster. | | `v6` | Specifying v6 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.2 and is supported on the cluster. | | `v7` | Specifying v7 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.3 and is supported on the cluster. | | `v8` | Specifying v8 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.5 and is supported on the cluster. | - *OBJECT*, an object class such as `views`, `quotas` or `snapshots`. For example, to explicitly request the version of this endpoint from the current version API, you would use this URL: ``` https://VMS_VIP/api/v8/snapshots/ ``` This URL would default to the oldest version of the snapshots API endpoint: ``` https://VMS_VIP/api/snapshots/ ``` ### HTTPS Encryption The VMS API supports requests only over the HTTPS protocol, the secure version of the HTTP protocol in which requests and responses are encrypted. In the above cURL example, the flag `--insecure` is used to skip validation of any SSL certificate that VMS may have. In order to benefit from the secure aspect of HTTPS, you will need to ensure that VMS has a valid SSL certificate installed and have your clients validate that certificate in each request. If an SSL certificate was not yet installed on VMS, you can use the VAST Web UI to install such a certificate. VMS will present the installed certificate to all clients during the SSL handshake that takes place to establish the HTTPS connection. ### Controlling the Response Pagination of lists of objects that are returned in responses is controlled by optional query parameters. Best practice is to pass pagination parameters with any code that accesses any endpoint that returns a list of objects. For some endpoints in this version that return lists of objects, pagination is enforced with a default page size. There are also endpoints for which pagination is not enforced, but requests that do not request pagination fail if the response size exceeds a threshold. These include breaking changes in VMS 5.5. For details, be sure to review [Breaking Changes](/api-5-5/apidocs/cluster-api-change-history#breaking-changes) as well as [Enforced Pagination on Selected Endpoints](/api-5-5/apidocs/cluster-api-getting-started#enforced-pagination-on-selected-endpoints) In addition to pagination, you can also use query parameters to limit the response to specific fields and to limit the response to a specific page of a paginated response. #### How to Append Query Parameters Query parameters are appended to the URL of a REST API request. To append one query parameter, append a `?` and then the parameter, and its value, like this: ``` ?parameter=value ``` Use an ampersand (`&`) to separate each subsequent query parameter: ``` ?parameter1=value1¶meter2=value2¶meter3=value3 ``` #### Query Parameters for Pagination The following query parameters control pagination: | Description | Query Parameter | Values | | --- | --- | --- | | Paginate the results. | `page_size` | Number of results to include per page. For example, to return ten results per page, specify `page_size=10`. | | Return a page other than the first page of results. | `page` | Page number to return. For example, to return page 2 of a paginated response, specify: `page=2` | A paginated response returns the count of results, an indication of whether there is a next and a previous page in the response, and the actual results are encapsulated in a results field: ``` { count: 15, next: null, previous: null, results: [{id: 4, guid: "588fec4a-aaf7-4296-b43f-4db288469d4e", name: "export-4"}] }, ``` Without pagination (not recommended), the response is returned in the plainer format: ``` [{id: 4, guid: "588fec4a-aaf7-4296-b43f-4db288469d4e", name: "export-4",… ``` #### Enforced Pagination on Selected Endpoints Pagination is enforced, with a default page size of 1000 objects, on the following endpoints: - `/openfilesqueries` - `/openfiles` - `/openfilehandles` - `/quotagroups/` - `/tenants/{id}/metric_label_values` - `/tenants/metric_labels/` #### Endpoints that Cap Page Size Only When Pagination is Requested The following endpoints, when version 8 is specified, limit the page size to 1000 objects when `page_size` is sent with a value greater than 1000. This is version-dependent, per endpoint: - `GET /volumes/` (v8 only) - `GET /blockhosts/` (v8 only) - `GET /blockmappings/` (v8 only) The following endpoints also limit the page size to 1000 objects when `page_size` is sent with a value greater than 1000, only in versions earlier than version 5: - `GET /userquotas/` (v1-4 only) - `GET /s3lifecyclerules/` (v1-4 only) - `GET /snapshots/` (v2–4 only. On v1, `page_size` is not capped; an unpaginated list is truncated to 1000 instead.) #### Limiting Response by Field To limit the fields in the response to a specified set, use the `fields` query parameter with a comma-separated list of field names that you want to include in the response. For example, to return only the `name` and `id` fields: `fields=name,id` #### Example For example, suppose the VMS VIP is 192.0.2.1, and we want to send a `GET` request to the `/vippools/` endpoint to return information about VIP pools. We could send the request to: ``` https://192.0.2.1/api/vippools/ ``` This would return a detailed response with the following fields for each VIP pool: ``` [ { "id": 6, "guid": "3a9858a9-df03-48bb-81b2-99b97e7ece69", "name": "REPLICATION", "url": "https://192.0.2.1/api/vippools/6/", "title": "172.21.100.180 - 172.21.100.184", "start_ip": "172.21.100.180", "end_ip": "172.21.100.184", "vlan": 0, "subnet_cidr": 24, "gw_ip": "", "cluster": "My Cluster", "cluster_id": 1, "tenant_id": 1, "cnode_ids": [ 1, 2 ], "cnodes": [ "cnode-1-21", "cnode-1-23" ], "domain_name": "", "role": "REPLICATION", "ip_ranges": [ [ "172.21.100.180", "172.21.100.184" ] ], "ranges_summary": "172.21.100.[180-184]", "sync": "SYNCED", "sync_time": "2021-06-12T14:20:16.662630Z", "vms_preferred": false }, ``` Using query parameters, we can limit the response to the name, role, start IP and end IP of each VIP pool, set the page size to three results and ask for the second page: ``` https://192.0.2.1/api/vippools/?fields=name,role,start_ip,end_ip&page=2&page_size=3 ``` Now, we get: ``` { "count": 5, "next": null, "previous": "https://192.0.2.1/api/vippools/?fields=name%2Crole%2Cstart_ip%2Cend_ip&page_size=3", "results": [ { "name": "user_a", "start_ip": "172.21.111.20", "end_ip": "172.21.111.32", "role": "PROTOCOLS" }, { "name": "plan_4000", "start_ip": "172.66.66.1", "end_ip": "172.66.66.200", "role": "PROTOCOLS" } ] } ``` ### Permissions Requests are authorized according to the permissions of the VMS user that you use to generate the access token. VMS controls user permissions using an RBAC (role-based access control) mechanism. See [Managers](/api-5-5/apidocs/managers) and [Roles](/api-5-5/apidocs/roles). As a security best practice, consider having your script authenticate to the API with the most RBAC-restricted user that can access the range of functionality that you wish to implement. ### Error Response Codes The VMS API uses conventional HTTP response codes to indicate the success or failure of an API request. ## Authenticating API Requests Almost all VMS API requests require authentication. The VMS API supports authentication secured by API tokens over HTTPS. This is referred to as *ApiToken* authentication in the reference documentation per endpoint. Besides support for API tokens, the VMS REST API also supports authentication with [JWT tokens](/api-5-5/apidocs/cluster-api-getting-started#using-json-web-tokens-for-authentication) and with basic authentication. When authenticating a request with basic authentication, you need to supply your VMS username and password. To authenticate to a specific tenant, add the `X-Tenant-Name: <tenant_name>` header to your request where `<tenant_name>` is the name of the tenant. This is required for a tenant admin user or an application user. ### Obtaining an API Token Creating API tokens requires *create* permission for the *Security* RBAC realm. Tenant admin users can create tokens only for users on the same tenant. To create an API token, do one of the following: - Send a POST request to the `/apitokens/` endpoint. If you do not have a token (such as the first time you do this, to create a token for yourself), you can use basic authentication, supplying your own VMS username and password to authenticate the request. For example: ``` curl https://11.22.33.44/api/apitokens/ \ -X POST -u : --insecure \ -H "Content-Type: application/json" \ -d '{"name": "By_Curl_for_admin", "expiry_date": "30D", "owner": "admin"}' ``` If you are authenticating to a specific tenant, add the `X-Tenant-Name: <tenant name>` header. For example, for user `tenantadmin1` authenticating to the tenant `t1` with password `mypassword`, creating a token for tenant admin user `joe` on the same tenant: ``` curl https://11.22.33.44/api/apitokens/ \ -X POST -u tenantadmin1:mypassword --insecure \ -H "Content-Type: application/json" \ -H 'X-Tenant-Name: t1' \ -d '{"name": "JoeToken", "expiry_date": "60D", "owner": "joe"}' ``` The following similar example authenticates to the same tenant `t1` using an existing token for the requesting user (see [Authenticating a Request with an API Token](/api-5-5/apidocs/cluster-api-getting-started#authenticating-a-request-with-an-api-token)) and creates a token for the tenant admin user `joe`: ``` curl https://11.22.33.44/api/apitokens/ \ --header 'accept: application/json, text/plain, */*' \ --header 'Authorization: Api-Token 0MivCn7o.hYveqY36ZMKJhr8VRYyO8UDXCtPVUje7' \ -d '{"name": "JoeToken", "expiry_date": "60D", "owner": "joe"}' ``` The response returns the token ID and the token: ``` {"id":"0GuvCn7o", "token":"0GuvCn7o.gYertY36ZMKJhr8VRYyO8FGKCqPRUre7"} ``` The token cannot be retrieved again. - Connect to the VAST CLI and use the `apitoken create` VAST CLI command. ### 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 ``` For example, this call to change the expiration period of an API token is itself authenticated with an API token in an authentication header: ``` curl https:///api/apitokens/0MivCn7o/ \ -X PATCH --insecure \ -H "Authorization: Api-Token 0MivCn7o.hYveqY36ZMKJhr8VRYyO8UDXCtPVUje7" \ -H "Content-Type: application/json" \ -d '{"name": "Modified_by_rest_with_auth", "expiry_date": "1D"}' "API token 0MivCn7o has been modified" ``` ### More about Working with API Tokens - The default and maximum expiration period of a token is the password expiration period, if enabled. If disabled, tokens do not expire unless an expiration date is set. You can change the expiration period of a token with a `PATCH` request to the `~/apitokens/{id}/` endpoint. For example: ``` curl https://examplevms.com/api/apitokens/swpkos3d/ \ -X PATCH --insecure \ -H "AUTHORIZATION: Api-Token swpkos3d.ei9XbTD7vIWpxhnkFT0GF4Hxf2I34KyS" \ -H "Content-Type: application/json" \ -d '{"name": "Modified_by_rest_with_auth", "expiry_date": "1D"}' "API token swpkos3d has been modified" ``` - The default naming convention for API tokens is You can customize this in the POST call. You can also change the name with a `PATCH` request to the `~/apitokens/{id}/` endpoint. - To revoke an API token, send a PATCH request to the `~/apitokens/{id}/revoke` endpoint, where `id` is the API token ID. (requires *delete* permission for the *Security* RBAC realm. ) For example: ``` curl https://examplevms.com/api/apitokens/swpkos3d/revoke \ -X PATCH --insecure \ -H "AUTHORIZATION: Api-Token swpkos3d.ei9XbTD7vIWpxhnkFT0GF4Hxf2I34KyS" \ -H "Content-Type: application/json" "API token swpkos3d has been revoked" ``` The API token is archived and becomes invalid. - To list API tokens, send a GET request to the `~/apitokens/` endpoint. It is possible to do this for a revoked token. > [!NOTE] Listing other users' API tokens requires *view* permission for the *Security* realm. For example, listing for a specific owner (`userX`) and including archived (revoked) tokens: ``` curl https://examplevms.com/api/apitokens?owner=userX\&archived \ -X GET --insecure \ -H "AUTHORIZATION: Api-Token RWDLanfS.9sYRGMD8tbzjhICbU9oeAXKcolsiDIs1" \ -H "Content-Type: application/json" ``` - To get details of a specific API token by its ID, send a `GET` request to the endpoint. You can choose whether to filter by a specific owner and whether to include revoked tokens in the listing. (Listing other users' tokens requires view permission to the Security RBAC realm.) For example: ``` curl https://examplevms.com/api/apitokens/swpkos3d/ \ -X GET --insecure \ -H "AUTHORIZATION: Api-Token v3tGcvW2.SnoAXYrNHHpyapAcl84xO6zHeISMROkK" \ -H "Content-Type: application/json" ``` Example response: ``` {"id":"JlcAkevs", "hashed_key":"sha512$$2f04a83e525dc54641a7fbd883040cd927ee277945a3df968f185ce03428049b7b07c5463f86e38b9edb487038007772c4783f1d71a0b53162afb3b3a83a5eae", "created":"2025-02-23T14:14:07.194696Z", "name":"admin_api_token", "revoked":True, "expiry_date":"2024-10-15T12:40:41.477484Z", "revocation_time":"2025-02-23T14:22:59.971748Z", "owner":"admin", "last_used":null} ``` - The maximum number of tokens per VMS manager user is five, by default. The limit is configurable with a request to the `/vms/{id}/set_max_api_tokens_per_user` endpoint, specifying `max_api_tokens_per_user`. For example: ``` curl https://examplevms.com/api/vms/1/set_max_api_tokens_per_user \ -X PATCH \ -u : \ --insecure \ -H "Content-Type: application/json" \ -d '{"max_api_tokens_per_user": 8}' \ ``` ## Using JSON Web Tokens for Authentication The VMS API supports authentication secured by JSON Web Tokens (JWTs) over HTTPS. 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 minimal time for the requesting user's identity to be exploited. The refresh token must have a longer lifetime than the access token. You can use it to request new tokens. You can then use the new access token to authenticate further requests. ### Authenticating Requests with JWT Access Tokens The VMS API also supports authentication secured by JSON Web Tokens (JWTs) over HTTPS. 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/obtain-json-web-tokens) endpoint. You need to pass a VMS username and password as the required body parameters. For a new VAST Cluster installation, you can find the default VMS user credentials here: [Managing VAST Cluster Passwords](/documentation/docs/managing-vast-cluster-passwords-55). If user credentials have been changed via VMS GUI or CLI, you'll need to supply an existing set of user credentials. Requests will be authorized according to the requesting user's VMS permissions. 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* resolving to your cluster's VMS VIP, your user name is *admin* and the password for admin 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":"admin","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 ``` See also [Making API Requests](/api-5-5/apidocs/cluster-api-getting-started#making-api-requests) for more details about making requests. ### 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 newly 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/refresh-jwt-tokens). Pass the last refresh token returned by the last refresh request as data. The response is a new access token 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 ``` ### Changing the Token Life Spans To change the lifespans for access tokens and refresh tokens, send a PATCH request to the `/vms/{id}/` endpoint. For the access token lifetime, pass the `access_token_lifetime` parameter. For the refresh token lifetime, pass the `refresh_token_lifetime` parameter. ## mTLS Client Certificate Validation VMS can be configured to require clients invoking the VMS REST API to present a client certificate. The requirement applies to any client connections used to make REST API calls to the VMS, including those used for accessing the VAST Web UI. To configure client certificate validation for VMS REST API calls, obtain a CA certificate (and a key) and upload it to VMS as the VMS mTLS certificate. You can do this through the VMS REST API by sending a PATCH request to the `/vms/{id}/set_client_certificate/` endpoint. After the VMS mTLS certificate is uploaded, the clients are expected to present the same certificate as the one uploaded to the VMS, or a certificate signed by the uploaded root certificate.