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 the Veeam Service Provider Console REST API, clients must first authenticate themselves. The Veeam Service Provider Console 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 must be used in all requests. Access token expires after 1 hour.
Refresh token is a string that represents authorization granted to the client and can be used to obtain a new access token when the current access token expires.

The Veeam Service Provider Console REST API authorization process involves the following procedures:

Requesting authorization
Using refresh token
Performing logout

Requesting Authorization

To obtain a pair of tokens, the client sends the POST HTTPS request to the Veeam Service Provider Console token path. The request body must contain credentials of a user with the Veeam Service Provider Console Portal Administrator privileges.

Authorization and Security Note:

Simultaneous sessions initiated in different applications under the same user credentials may interfere with each other. To avoid unexpected logout, use a different user account for every application.

A successfully completed operation returns the 200 OK response code and an access and a refresh token in the response body. The client inserts the access token in headers of further requests to the Veeam Service Provider Console REST API. The refresh token must be saved locally.

Authorization and Security Tip:

To learn how to authorize your access using an application, you can review the Example Requests and Responses section. Alternatively, you can use Swagger UI.

Using Refresh Token

To obtain a new pair of tokens in case the access token expires or becomes invalid, the client sends the POST HTTPS request with the refresh token in the request body to the Veeam Service Provider Console REST API token path. A successfully completed operation returns the 200 OK response code and a new pair of tokens in the response body.

Performing Logout

When the client finishes working with the Veeam Service Provider Console REST API, he logs out by sending the POST HTTPS request to the v2/accounts/logout path. A successfully completed operation returns the 200 OK response code and the Logout successful message in the response body.

Example Requests and Responses

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

To obtain an access and a refresh token, the client sends the 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 password value must be specified for this parameter.

username and password — credentials used to access the server; in this example, vspc\administrator and Password1 are used.

Request:

POST https://localhost:1281/token

Request Header:

Content-Type: application/json

Authorization: Bearer

Request Body:

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

The server sends a response in the following format.

Response Code:

200 Success

Response Body:

{

"access_token": "TveNSjnPynfSIDwOwVoeuAXoX7KVCSb46soAUw_f9vcyu59LGk9JpgP50mp5qMn0rkK88n7tsYwD8Aoc_yvJ72E83kCy9QWi6sCeR55iWInpyhYNbsdyy98XITG1LbLku7_yiV5DVI47oa1mE5iHuNW6-JQTeo8bGTkgUZ22_sSAWD4E6nxRdtyMJntVjJ7GqCkTxdaWbqfknOJgyJz8UVkI8xHuS7LlgeZtamotaFq2Q55IO6wp9ij37NMKkurjujGMtyfDM4BinyesB5w6QL0MgLCaP-q909wXRoOpk9cLG4tRAGe0LFT_rjgE9OVdON4J-LExhD-Awxgr9lIQqj3oC2thAUmTYyjQJ0NBffHASnZ7sMZF5KCJEJXQTt84oMACOFCNG2Fityr_xyMs_TQ7F_if-Qax5QyvdgvIhnaU4iZu6-AT2VqEcUKMheQaQrzghL28SzdhPWcCcJDMtl0gEN6apjkZCo31PVGNPY_ZeEdDftFM53XW9Xx2n3Cr1gjKcqyw3xvst55gsJRc5QtyR9qnamsl1g31SUa17hlZ3FBJ9FbBOnShegXy_VcunE60YbB2gQyj6gyWdUGGWWBRMyqPO9ZGQ49CowIC-zh2Na1lM8Gl5LK6QPXeGTy17Zcs4zJUo7f1N1F8ZF6e0uiMvy3Mndz-Fka80uQ5f3XUIuK6oDUzlc_0WOdo9RFVX0U5SASUszMpsPFgAAIu9qXvy5Ma75oKGhyNv9h2PlH-Ew3GOXfedi50kpDTRuiL_ETgod5tTem2uW3AdptXD6CxtC9f6oxIkCR5qZRiIcqAZlBqJ9LBrpEPKDwlI5B7cG5iDU5KaZBceEzNL5A0XmwYM-krIntDNVExWtKJlU80z8J15w4FROpOT-5oHOXavOufApDfrjvkr5Yj5fWcBq3PO86WtHn8u1NPx1RnuIKqZk5Uf4d1uhY1IkJloC_WE4YsfQBi0Rn_G4sKEw_tQyNtASGpivwz7qVbV930ENz9d0X04NM8Z5jJbBcblMWpURFbI5qMIuQGQebdN7nRpsujh8QOGWR8zJb981HuaZDL48FzUQ0UfW3MvtwW2ghAGSpiPq5hIwNOBoZyEaHOokGUKDzPs8FBk0s3CH1ByzVdrH7Xa03YI14j2i1kofRYkUUlyczhDoT1qDzLj35zQWZnAHHPW8FW30RTJy7wnxeILeUDXZbZ2hzo7W3-NSB3ilXsghU4ZFvW3yPqY4wY9ti9oBVY2F3PRYI4E7tN1ZH2ZxbOjLJmzTBbirI8PjVs_a-1kO9n2IoaUWStUD8w-5lhck_aTpSG_FFxYG-qz9wHUMWLOEgRDExsxgLCuO9LB5Avht6bEdXkht8prvabo4Rpj0EBtuhXNMkU3y8AEPjbzc5f4mNFQq4swsSg82ysh1uL5B4wyX1u7jR1illhNhZsvbNUSclZeDae5d0sK8RsGqA7TbcoxGrWvYxvqROkHwd5Cf9KgbBQqT_wWWk71fVk_D-PgeFbDOWeS32gAtH5PqiBYWxtSKx11rYptEpz3roxcMb02VUVzf95katVMgbFS9hrv3y1ZZcHKL0xy5wpjDKIaTJi-2vZ-xq-_STw-84nJIYG-qVzH4U4ecMLyrnDNEyegBsg3-_s5wjJqLuYhT4BtFf9sJLibT3Y9MmsrkJBYRyyejtZeKjQ2MuHpVXdzIsIardrWdW-WqJLgq98NQvNG3XVIsYZagB_dyHMOWOwbfdr13dL4O6wRiAG4sPyZQ8B0TAJrwV_IDcza7F1Qu_iPZyLakxgcnBFgSf46nlHn1ujB1_bJPkrFkkB115epAj4Cmh71r3LqvScfQO-H-dYye6I6JnSnSAPisRf",

"token_type": "bearer",

"expires_in": 3599,

"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDU5-TIyIiwiZXhwIjoiMTU4MzIzMjMyMiIsInN1YiI6IjI5MmEwYmRkLWFlMmQtNDE0OC05N2YzLTYwM2JlMTZmMjQ2NSIsImp0aSI6ImY5NzdmZDhlLWU0ODEtNDk4Yy1hMjUwLTNmZDlkMjZhODMxZiIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYXRvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMiOiI3NTM0YjQ3NC1jNzM5LTRmN2QttpE1Yy1hZDE5OGI4NjYwYzUiLCJzY29wZSI6IjIiLCJraW5kIjoiMiJ9.LueaQPc5VejcfC37_fhn-coAy-Gc7INkdKZVLkhRRbxdIRAV-P5c_1VpCRjR3MGpDBUoPcvKx-IiQbNDA9GyhsBz_2uSFB-746WgYTnXSZyvHrzFJBH1HW24Lpx2gRfCiYJCX6-RB8xxifW7ngIxbrTz0VKNaSTgCuO-vOFp7MHzfD1fyUy9SHKiqMs29NVQtJW3iyoAY37ysDrZDuh0ElSuqGUQKddFAmjDu2hiTdxUxvxRW-WZo6r3qD4uDes3CHKY2CXK3WZ3iaJXzrw9qLsJUPoM1Ll3INBRvUyI32AQ90AIu9ZrtsFPJSVAVA6p5KoFPPl5yyhTG5u7QK2zJg"

}

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 values for the parameters:

grant_type — to refresh the token, it is required that the refresh_token value must be specified for this parameter.

refresh_token — the previously saved refresh token.

Request:

POST https://localhost:1281/token

Request Header:

Content-Type: application/json

Authorization: Bearer

Request Body:

grant_type=refresh_token&refresh_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDU5NTIyIiwiZXhwIjoiMTU4MzIzMjMyMiIsInN1YiI6IjI5MmEwYmRkLWFlMmQtNDE0OC05N2YzLTYwM2JlMTZmMjQ2NSIsImp0aSI6ImY5NzdmZDhlLWU0ODEtNDk4Yy1hMjUwLTNmZDlkMjZhODMxZiIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYXRvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMiOiI3NTM0YjQ3NC1jNzM5LTRmN2QttpE1Yy1hZDE5OGI4NjYwYzUiLCJzY29wZSI6IjIiLCJraW5kIjoiMiJ9.LueaQPc5VejcfC37_fhn-coAy-Gc7INkdKZVLkhRRbxdIRAV-P5c_1VpCRjR3MGpDBUoPcvKx-IiQbNDA9GyhsBz_2uSFB-746WgYTnXSZyvHrzFJBH1HW24Lpx2gRfCiYJCX6-RB8xxifW7ngIxbrTz0VKNaSTgCuO-vOFp7MHzfD1fyUy9SHKiqMs29NVQtJW3iyoAY37ysDrZDuh0ElSuqGUQKddFAmjDu2hiTdxUxvxRW-WZo6r3qD4uDes3CHKY2CXK3WZ3iaJXzrw9qLsJUPoM1Ll3INBRvUyI32AQ90AIu9ZrtsFPJSVAVA6p5KoFPPl5yyhTG5u7QK2zJg

To log out, the client sends the POST request to the v2/accounts/logout path.

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

Request:

POST https://localhost:1281/v2/accounts/logout

Request Header:

Content-Type: application/json

Authorization: Bearer Ike0PdTbUl3yoCpM2Rrxpl3pjTAk5r2J4Sg1vv7AA356hFd6BJUZv77fJMAXAisFWMNnCghkG98AhOdG9iZ-2AcDWjT5rQWAd6mk7OtdV4RjE4vrUJ8Eu9T-AhZvjwxf_1IYM6SyzCMYM69pTHpkUod8mHz2zSaBQwXrszIuoo4wq2Rmo0Oc4yz_V2-Gp4b4XJhYbTGDQlEdEB6tHGdz2_NCCKMtCFD0e1z9tdcwD0aaMuTfLfyOsezJTYQ3Qbq75rVWbsIiQEWKfIAWwdcVYUvd_62TJXJH1ToLd3e5DI2LBa7tAUgEca6VUWAqMR9dMQkViy2To35ZvznP6wShxZkVp5t6q-3-0cMq0w930OOuPXyfGYWrGz53pyxRRn5cJyvL9ZDecywfzONFxwoJBf6CVpy9mdQT3BKOhiQwlSm_vxTW7rauW9v2KhQcZSBcQBrQIXmNDbtKniFBv869PsTEe4WMh8JrsL0OgwjR4UMKylv57DZlVJ1H7t4aBO-sK3ZXPp1uZWfIWeVf1N6UQocw2z0bq1KE66auKIO_J6-JghrzQeBGwxv3hes5A92-L0q4SUhD3kEaPdqdig1asqGbyhkxEFSmAHtQ_yGn4AecvfITUdxWxbYtAn_2Stfa-x_PRBnR5OvwjrfKYUDeFmICgmYmq8bUy_IOZRhuMGkSWW9pKV3lez4NGLnh5cj6Rsd26gyqa8hkBDakd3t1h01N0g2FKxUNK7YLgLTQ6sJJpSI6Q0HjPOq7a5scwUBTywqrCiq2iHnvJM2LeaMmUMD0mvFie97sV-s0ZdrYQjqS9nRUfsQZclLBG_xv6ByJ6zbx86Sty6W7EmD7HyG8VnYR3uwJe8pkZuJlCP8GvOtrLmt-tr6mdgTgSFM-MnyQHrdABnY8ZSEUwzApwuKYBrTXv_6YS-RMyELscOmyjbEkldXFRzZk8MaDdFW2pCIqyUb0a0GelrQuiGSRQDnUta1nqUowM1MaoUOUntfOcbHyN3_HnnZdLZp0FnZhLLkfonYMObYg4GqRfLkNVgucK-9D374I719d8yBAympvTzA6RK5tcaXzPpKmskrEk52PSNS1f3FuHcIMZKCVWBptovBnNwTXPnJaK6STxYWtK1uzTI3MMqZR-WBh4Ghat4a4ArNQ-BkT_REfkYpfhwDyQLgrl333sXq2A-2rxvnLA6MYliiPDGCdddm4K-Y14WHN6inXwCjVl08Dv7dOpxaVkYPlSL6D_nTM2Tdrhebsr9-j0p4e27Swc2BMT3l2PvnJ3N0VqrahHBvhhwdPNfCBBzxlp8fSmuBnW1_oyvpSNrK3h2IEtR9LbScC7r1zdwnbNt2Ap0EY5C0vmmoziS9DoAvYcpJnE-r-VlxQx_KfBSYAPe2RMrUlRGRWMuRHEofSiGDkD7-K8E1zZgdoPG2cB6aduiZIbpK3UbZZcSJWuV8s-3t2Rfv6cc1HWpWy-k2FvIjGYlJ0nsBUV6GaSeuMjQ-4ZhilT9OvfX_p0WFCN-viDt6lML3D0nchwjzOiunXCAoylEUqxVz1R0Y-lrnQ2lTRx_ZXd0hRuL5Fav8cR1qkrmnexRwkTIjkOdAPPQyLafdHNKvfQEjHGYhTpI6HchxF8gZJ3CWeLifmf6FZWESz8hFlapjzKKC1aO3GwlQFnNgX8blXUMgXELe3NxJDY0GfK8U_1a1bqS-ZDf0QwoAbuKyXeoyMm5VO5l_1s0hOjDJpaPFL-Va0cMm_A59hqAjFZHiGmuCBwD_A2iKejUE6YhxqLoB3fQ84zxlgw2D9SQ5NCTdxbVhNCbm6A9H0hBG9HspYZ1SbvNkDMA48LMICnIeidBF4ZZ4bKpKFdT09

The server sends a response in the following format.

Response body

{

"message": "Logout successful"

}