Authorization and Security
To start working with the VAO REST API, users must first authenticate themselves. VAO REST API authorization process is based on the OAuth 2.0 Authorization Framework and involves obtaining an access token and a refresh token.
- Access token is a string that represents authorization issued to the client and that must be used in all requests during the current logon session.
- Refresh token is a string that represents authorization granted to the client and that can be used to obtain a new access token if the current access token expires or becomes lost.
Veeam Availability Orchestrator REST API authorization process involves the following procedures:
To obtain an access token and a refresh token, a user sends the HTTP POST request to the VAO /token path:
The request body must contain the credentials of an account with the VAO Administrator or Plan Author privileges. The user name must be specified in the DOMAIN\USERNAME format.
For more information on how to assign VAO user roles, see the Veeam Availability Orchestrator User Guide, section Managing Permissions.
Simultaneous sessions initiated in different client applications under the same credentials may interfere with each other. To avoid unexpected logout, a user can create a dedicated client account for each application. For more information on how to work with client accounts, see Working with Clients.
A successfully completed operation returns the 200 response code. In the response body, VAO returns an access token, its expiration time (in seconds) and a refresh token. The user inserts the access token in headers of further requests to the VAO REST API. The refresh token must be saved locally.
By default, the VAO REST API access token expires in 15 minutes. You can change the token lifetime policy to meet the necessary security requirements. For more information, see Configuring Token Lifetime.
To obtain a new pair of tokens in case the access token expires or becomes lost, the user sends the HTTP POST request with the refresh token in the request body to the VAO /token path. A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.
If you lose the refresh token, you can log in again under the same user account and get a new pair of tokens.
To log out, the user sends the HTTP DELETE request to the api/token endpoint. A successfully completed operation returns the 204 response code.