Help Center
Choose product document...
Veeam Availability Orchestrator 2.0
REST API Reference

Authorization and Security

To start working with 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.

VAO REST API authorization process involves the following procedures:

  1. Requesting authorization.
  2. Using the refresh token.
  3. Deleting clients.

Requesting Authorization

To obtain a pair of tokens, 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. For more information on how to assign VAO user roles, see the Veeam Availability Orchestrator User Guide, section Managing Permissions.

A successfully completed operation returns the 200 Success response code. In the response body, VAO returns an access token, its expiration time, a refresh token and a client ID. The client ID is used to identify this user as a root VAO client. The client inserts the access token in headers of further requests to VAO REST API. The refresh token and client ID must be saved locally.

Simultaneous sessions initiated in different client applications under the same credentials may interfere with each other. To avoid unexpected logout, the root VAO client can generate a dedicated child client account for each application. Child clients inherit the root client permissions in VAO REST API.

Authorization and Security Note:

Child client accounts cannot generate their own child client accounts.

To learn how to authorize your access and create client accounts, see Example Requests and Responses. Alternatively, you can use Swagger UI.

Using Refresh Token

To obtain a new pair of tokens in case the access token expires or becomes lost, the client sends the HTTP POST request with the refresh token and client ID in the request body to the VAO /Token path. A successfully completed operation returns the 200 Success response code and a new pair of tokens in the response body.

Authorization and Security Note:

If you lose a refresh token, you can log in again under the same user account and get a new pair of tokens. In this case, the client ID will remain the same and you will be able to continue working under the same client account.

Deleting Clients

If a client is no longer needed (for example, when the client finishes working with VAO REST API), the client account can be deleted by sending the HTTP DELETE request with the specified client ID to the VAO /Clients path. A successfully completed operation returns the 200 Success response code.

Authorization and Security NoteS:

  1. A root client can delete both his own client account and all related child client accounts. A child client can delete only his own client account.
  2. When a user deletes a root client account, all child client accounts created by this root client are deleted as well.

Example Requests and Responses

The following example illustrates how a user and the server communicate using requests and responses.

  1. To obtain an access token, a refresh token and a client ID, a user sends the POST request to the /Token path.

In the body of the request, the user specifies the following parameters:

Request:

POST https://uwin2012r2.n.local:9899/v2/Token

 

Request Header:

content-type:application/x-www-form-urlencoded

 

Request Body:

grant_type=password&username=vao\administrator&password=Password1

The server sends a response in the following format.

Response:

200 Success

Response Body:

{

"access_token": "AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAAC3LPv4uyWic8JgLrAwRnqHWbbXGSw8T9HYq_OrvrRHnAAAAAAOgAAAAAIAACAAAABhMkjC7oHJlJzbn7SdlYJqcg-K5BPmqI0dCvwjbrmPVKAAAADdNJGCbOZNmRdv_XoGeKAqa-cu_yOvlK0A_I7jAbWCSW0EOqbw0Ttxa6NNbc9cBk_EfhJsMZJkU2RZ_qL0buOxyM7H78YhatVNxOzDkoAxq-wZNgUjTYkXgyah5fdfLkYu7MebZ8wrs0XTr0tfrlqoqx5FVZ5Je9DMtQ-JjkDe3CWlxrr9JXMSgtNk-9JR5VTNjcPHmu3eGmrfobq7elFyQAAAAA2DuwJ_uNEQaiUYBTO6uSYJA68Kazl_mIwAX4ru9xqZxWoMAg6QyXwt2zJweZVPUR53ORykv5tRWgtEDE-a6Ec",

 "token_type": "bearer",

 "expires_in": 3600,

 "refresh_token": "AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAABkQCXl2L8XsqEho_aGPHRLCwf0o0wtMCdh12zC5kGWoAAAAAAOgAAAAAIAACAAAAAhmMlzCisilYoq3R7wFVAIojXucjNitxNQSixO0hLFDKAAAAD1WPq8tIEanVDLUJ2sCoOgs01g7vrvuwQ6gw0DW00pAF_tnWeFCx8qbTr7kEawDwEvqG9buAdWypajB-n_TXERMlHyyhB72HlXWQyBsrRtbzleQmd76F8p6hwGaBqjzJrlqYKktSLNZayAsImjq2bbUSf9Nlkqp7EkjJNHN-VnCQzy1hI_QY67c3-hh1SoYg2iSFYyNlGyID20xVaWU82WQAAAACH_o7QU8minqZpxdz93aXI81ylr3Fy1BY1YzT95hoTg7PMeUwZMr1xTi0SYiid9IS3i0Zbpjt9pOWN1ToNZ6Nw",

 "as:client_id": "21a02e38-8027-4b31-962e-966d05934a8e",

 ".issued": "Mon, 25 Mar 2019 11:11:40 GMT",

 ".expires": "Mon, 25 Mar 2019 12:11:40 GMT"

  1. [Applies only if a dedicated child client account is required]

To generate a child client account, the root VAO client sends the POST request to the /Clients path.

In the Authorization header, the root client specifies the currently valid access token in the Bearer <access_token> format.

Request:

POST https://uwin2012r2.n.local:9899/v2/Clients

 

Request Header:

Authorization: Bearer AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAABHjCgvTRsG2b1YqhiypnWZsYZxO4vBwZcXi_PtalWPGgAAAAAOgAAAAAIAACAAAABiEo4routJgEeka16SY4lwARtl8le4GI5g0e9B6CwKC6AAAABZ2GJ465k_4VK2DNHaZgjMTa9S7a9b3nFlgr6CHN5F_RznzatmDP_0K7zG2z-xkMke-0i9gRwUEr9K_n7ZqIy96ZWDQAi6WPHBPufx37Ka5kN3wwujiqJpVALQWrRhg6MckVcFTMpap3CTP1UpGFNaVgIUydDlFv3-xXu8ifTX7aEWqa6aZtMIkDuGQiCB9mcellW4UTCGhw-j9DaEtfWnQAAAAO8Y5Uculr7q9BSVB1r5hzChNItOYGUnbsO_DzeSxq0oAurnBDlxsSJfiz6ZAXfahYWDOgajiCVoS0KbUtHXunk

The server sends a response in the following format.

Response:

200 Success

Response Body:

{

"client_id": "58b91a67-4aca-490f-aeac-2ea11eadceaa",

 "client_secret": "iGuL5owQoVbN/RfaWYPTjh4QHT+1ylQlqiwKR+PS/jA=",

 "access_token": null,

 "refresh_token": null

}

  1. [Applies only if a dedicated child client account is required]

To obtain an access under the child client account, the client sends a POST request to the /Token path.

In the body of the request, the client specifies the following parameters:

Request:

POST https://uwin2012r2.n.local:9899/v2/Token

 

Request Header:

content-type: application/x-www-form-urlencoded

 

Request Body:

grant_type=client_credentials&client_id=58b91a67-4aca-490f-aeac-2ea11eadceaa&client_secret=iGuL5owQoVbN/RfaWYPTjh4QHT+1ylQlqiwKR+PS/jA=

The server sends a response in the following format.

Response:

200 Success

Response Body:

{

"access_token": "AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAAByWMrKNLapPuONlSNncd9XR7IACDcni3Ga1zEovMieagAAAAAOgAAAAAIAACAAAABEAs1Bh1r9ewxuymhYtNlxC3iWDTpVOQECINX8XxQxQKAAAAB_J1dgkVZsnnbRgRPjW_gVjADHL6NDPASSMRaAFYHgEeCCFHXQYBEL2BxebIkPJOrg3-yMvwn63URkL8zMmhoDpvyHupiJVUry-W5Wm3RMQ1ZrXoEzwUWZyJ9Yt_4a6Jwyiq5tbXVp2G1dA6ckJgF0rPkmHr3-9RvBGAjHZs7tVP54P2deJug_4XTgupSdebpGziDStvLVlBwzMS-lPj6kQAAAALZX0e5FqT2i7XMiPaaEJoIeXkBGKWzioVBrX44Xmbo8LaJRO3HtP3V1z5zT2zvIaeWmNVhKLk0M_p8bY6vaQ4Y",

 "token_type": "bearer",

 "expires_in": 3599,

 "refresh_token": "AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAAAUE2R6uAGbTBwJSeYqujT2S6_HBrGhGsRyyRB3nOt7IAAAAAAOgAAAAAIAACAAAAChyQ9Agp86l1tYTX-oyXV_1oWZksKK4HNNYXpldQAQw6AAAABtdoprD46bAvC9cXjGkfXm3JuStP49H6f8WIc4NuQcevlINLKFrw4fKBicdvX_ftB7N7SFmWTUkSOlLwsL43QBRpXE-5H_lx3YuKLFFNF6j3vlyAWfZAhtkevKvCjlB1kdYMiLBNS4ktYQc3Z8mIhq4jSXcNTQdkOut4kSwScf64S-6DhO9tHRnoKdS1RckRb5rIuR98k7ramw2Ei3CDKfQAAAAKeAaOIB0Sb8gZZLHg2cD0flgeVhhEbZw2YPYmuAWg7uLZBaxSfCporGHtz__jB6SRPUOJ-PTiUA4Mo-ftF0VDc",

 "as:client_id": "58b91a67-4aca-490f-aeac-2ea11eadceaa",

 ".issued": "Mon, 25 Mar 2019 11:28:05 GMT",

 ".expires": "Mon, 25 Mar 2019 12:28:05 GMT"

}

  1. To refresh a pair of tokens, the client sends the POST request to the /Token path.

In the body of the request, the client specifies the following parameters:

Request:

POST https://uwin2012r2.n.local:9899/v2/Token

 

Request Header:

Content-Type: application/x-www-form-urlencoded

 

Request Body:

grant_type=refresh_token&client_id=58b91a67-4aca-490f-aeac-2ea11eadceaa&refresh_token=AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAAAELmXi67xDVNTcKCsH6LF20knVa6FtA0_edygcO8YkjwAAAAAOgAAAAAIAACAAAAAVsdBUWqUV5DjnBqv7ODIIbcGcV_taiga53XwUO4R_urAAAAATknFUPnPhXR0eVK2Fqdtp6M_JNmk55F27W_N6fH_YRqjY3uoT1zj_8L8NGlbPWSeWwcZneyFpzShkN-irVqKhssgeNvmpVL915Syovr_P8P23f3x14_58ptGeMZi8XoPQuL6aYBaQtilEdsKpvvDM4k9UdFLJVQ0ZXDz4l6LxuPN_HinKfQMi7XZZkhHVyWF_3LLm5KmB5ekPa3mO3pPeeNVeqr2dh9QnxPmAG6nigEAAAAC6Ip02GkHm46QXW9neJPPWU7Wy8U4_c9bthNzDLztsuMG9MNJiHTH48qDrvT1_Yc1eSjFEdraZYrCOLCuCd1sh

The server sends a response in the following format.

Response:

200 Success

Response Body:

{

"access_token": "AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAABiorGyN_WFGdSCTmBA9GsUCvOJSARwxRNJGdMVSkwrKQAAAAAOgAAAAAIAACAAAAAwrFXl2LaUUoaVXdPt_ylD1guUHDNaE1VwApg_lcnjZ6AAAABNX3PsP2v_mIqIRBFgwbu-HipEQc0O-WIfgpBf3b2dBHQAAu3FzgMLdL0xkaFnZciYJP7mWUtd0-eHqN9FSm5kuQaTwXl3AeON2z8zQTYWE7irlfaSq3CV7tGV_Gkqitsxa4HnXLtXZIge9vScO03r9-b8Jsr6vtw3QKUpaCFGfdQ9cR4LkP737wnCV98EfPXvbHF05COZhQhDpdYODUk4QAAAADBeIcHrkZb8WRYDXDtBuXmz4FmRFhmYbAmeql6Wh5RCyUqBTXj-Ro2TSsS3Dt_1LZqQ3ZVPyfvudappNu2XxJ4",

 "token_type": "bearer",

 "expires_in": 3599,

 "refresh_token": "AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAAAmUUkuYkSmfaXGp0xfQZuSLf2d93cXsnvRxE8reTdgcAAAAAAOgAAAAAIAACAAAADuKZF1LS0Owl6KdVKAPJJpfjGK9_GHl9gb795x4lYnlKAAAACG7f8DUl9v0TsMc-5PkuVTGT0PCt3rpMFSn2VjWC6EhHmWoXFv17EQp959FWhCG6QwEn5I4RgOj2Zj50ZgK10BSorSci-JE7BSSEg_7HTc6nFcvXH29qswllutLzegZFovB5sSGy5uWFuvpgWdKBDFwFRfOvCzOyBgYZy7Bpel8G9mSWp-OcZaJk884FlNfsoEB3a6NH0NJE4siY2v3Zo3QAAAAED1DOW7XIIhFKGbbc4ZvCO6lTCOfehf1ohglBTqiPc8LFrdiM4XO7xIpknXc_53FNuO3Fs0j_fSsVbwDLInhPg",

 "as:client_id": "58b91a67-4aca-490f-aeac-2ea11eadceaa",

 ".issued": "Mon, 25 Mar 2019 11:46:13 GMT",

 ".expires": "Mon, 25 Mar 2019 12:46:13 GMT",

 ".refresh": "True"

}

  1. To get the root client ID and all child client IDs related to this root client account, the root client sends the GET request to the /Clients path.

In the Authorization header, the client specifies the currently valid access token in the Bearer <access_token> format.

Request:

GET https://uwin2012r2.n.local:9899/v2/Clients

 

Request Header:

Authorization: Bearer AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAABHjCgvTRsG2b1YqhiypnWZsYZxO4vBwZcXi_PtalWPGgAAAAAOgAAAAAIAACAAAABiEo4routJgEeka16SY4lwARtl8le4GI5g0e9B6CwKC6AAAABZ2GJ465k_4VK2DNHaZgjMTa9S7a9b3nFlgr6CHN5F_RznzatmDP_0K7zG2z-xkMke-0i9gRwUEr9K_n7ZqIy96ZWDQAi6WPHBPufx37Ka5kN3wwujiqJpVALQWrRhg6MckVcFTMpap3CTP1UpGFNaVgIUydDlFv3-xXu8ifTX7aEWqa6aZtMIkDuGQiCB9mcellW4UTCGhw-j9DaEtfWnQAAAAO8Y5Uculr7q9BSVB1r5hzChNItOYGUnbsO_DzeSxq0oAurnBDlxsSJfiz6ZAXfahYWDOgajiCVoS0KbUtHXunk

The server sends a response in the following format.

Response:

200 Success

Response Body:

[

 "be79c983-0ca9-4eca-94c4-b43f1f82212e",

 "b2845041-53ce-4335-b157-bcf9b08740c8",

 "98e3c3cc-5945-4b30-9e89-6066e5159502",

 "3ace3638-3810-4f0f-92e6-d700ad5df6ba",

 "06af349a-acba-4f42-9f81-721489bcae4c"

]

  1. To delete a client account, the client sends the DELETE request to the /Clients path.

In the Authorization header, the client specifies the currently valid access token in the Bearer <access_token> format.

In the body of the request, the client specifies the client_id parameter — an ID of the client to be deleted.

Request:

DELETE https://uwin2012r2.n.local:9899/v2/Clients?clientId=58b91a67-4aca-490f-aeac-2ea11eadceaa

 

Request Header:

authorization: Bearer AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAVKxp7agPW0-9sNr3uo1hmAAAAAACAAAAAAAQZgAAAAEAACAAAABHjCgvTRsG2b1YqhiypnWZsYZxO4vBwZcXi_PtalWPGgAAAAAOgAAAAAIAACAAAABiEo4routJgEeka16SY4lwARtl8le4GI5g0e9B6CwKC6AAAABZ2GJ465k_4VK2DNHaZgjMTa9S7a9b3nFlgr6CHN5F_RznzatmDP_0K7zG2z-xkMke-0i9gRwUEr9K_n7ZqIy96ZWDQAi6WPHBPufx37Ka5kN3wwujiqJpVALQWrRhg6MckVcFTMpap3CTP1UpGFNaVgIUydDlFv3-xXu8ifTX7aEWqa6aZtMIkDuGQiCB9mcellW4UTCGhw-j9DaEtfWnQAAAAO8Y5Uculr7q9BSVB1r5hzChNItOYGUnbsO_DzeSxq0oAurnBDlxsSJfiz6ZAXfahYWDOgajiCVoS0KbUtHXunk

The server sends a response in the following format.

Response:

200 Success

Veeam Large Logo

User Guide

Deployment Guide

Group Management Guide

REST API Reference