Authorization and Security

To start working with the Orchestrator REST API, users must first authenticate themselves. Orchestrator 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 Recovery Orchestrator REST API authorization process involves the following procedures:

Requesting Authorization

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

https://<FQDN>:<port>/api/token

The request body must contain the credentials of an account with the Orchestrator Administrator, Plan Author or Plan Operator privileges. The user name must be specified in the DOMAIN\USERNAME or USERNAME format.

For more information on how to assign Orchestrator user roles, see the Veeam Recovery Orchestrator User Guide, section Managing User Accounts.

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, Orchestrator 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 Orchestrator' REST API. The refresh token must be saved locally.

Tip

By default, the Orchestrator 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 Orchestrator /api/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.