Authorization and Security

In this article

    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:

    1. Requesting authorization.
    2. Using the refresh token.
    3. Performing logout.

    Requesting Authorization

    To obtain an access token and a refresh token, a user sends the HTTP POST request to the VAO /token path:

    https://<hostname>:<port>/token

    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.

    Note

    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.

    Tip

    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 learn how to authorize your access, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

    Using Refresh Token

    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.

    Tip

    If you lose the refresh token, you can log in again under the same user account and get a new pair of tokens.

    To learn how to use refresh tokens, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

    Performing Logout

    To log out, the user sends the HTTP DELETE request to the api/token endpoint. A successfully completed operation returns the 204 response code.

    To learn how to log out, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

    I want to report a typo

    There is a misspelling right here:

     

    I want to let the Veeam Documentation Team know about that.