This is an archive version of the document. To get the most up-to-date information, see the current version.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:
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.
|
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.
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.
|
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. |
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.
|
|
Example Requests and Responses
The following example illustrates how a user and the server communicate using requests and responses.
- 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:
- grant_type — the authorization process requires that the password value must be specified for this parameter.
- username and password — credentials used to access the server; in this example, vao\administrator and Password1 are used.
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" |
- [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 } |
- [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:
- grant_type — the authorization process requires that the client_credentials value must be specified for this parameter.
- client_id and client_secret — credentials used to access the server.
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" } |
- 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:
- grant_type — to refresh the token, it is required that the refresh_token value must be specified for this parameter.
- client_id — an ID of the client whose token has expired.
- refresh_token — the previously saved refresh token.
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" } |
- 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" ] |
- 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 |
