OAuth 2.0 Authentication

This authentication type is based on the OAuth 2.0 Authorization Framework.

To obtain a pair of tokens, the client sends the POST HTTPS request to the /token path.

OAuth 2.0 Authentication 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 Veeam Service Provider Console RESTful API. The refresh token must be saved locally.

OAuth 2.0 Authentication 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 /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 Veeam Service Provider Console RESTful API, they log out by sending the DELETE HTTPS request to the /users/{userId}/tokens path. A successfully completed operation returns the 200 OK response code.

Example Requests and Responses

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

  1. 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 in the application/x-www-form-urlencoded format:

Request:

POST https://localhost:1280/api/v3/token

 

Request Header:

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

 

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": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDA4MTc4IiwiZXhwIjoiMTA4MzAxMTc3OCIsInN1YiI6IjEzYTUyNjUyLTY5YmEtNDI4My04OGQwLTdiZGI1MDgzY2ZhNiIsImp0aSI6ImEwNWI4ZTcwLTU1ODQtNGM2ZS1hm4VmLTk2Yjk0ZGNhM2Q2NSIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYXRvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMiOiI3Mjk0N2RlYi1mM2Y2LTQ4ZWEtYWE0ZC0wOTJhOWZkNzBmNDIiLCJzY29wZSI6IjIiLCJraW5kIjoiMyJ9.n6cmkbX3dQsZdMR4V0IgEBfdyiSJ1FQByvdQVhSYbiHoAaYU1IF473qhRqJCt3IRkqfjMCtPmXzeWDXJ0pihOioiY4y8iqIGr7iQlS9nW-UDRj79NqiZQ-FZI1Jyre4HI3r4undfP9Y3BxSxswLD61XNGao1VWIDf2UdpTxIekimeaPS12Km0YY2prWp5jkvMHe5IR_JQWi6D-DeYf5Smdcn4fVNpsb327qdONf1Vp2pgkLuEZim33Two4r8cDXj3q6h2NCOnxf1wD3Kv5fvLxT33G6Ia37kiCjdwKI2MWlyppaoLj2IBGgVAxOzdIbtVVzQtvU7T0-2WSdfN3QzlA",

 "token_type": "bearer",

 "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDA4MTc4IiwiZXhwIjoiMTU4MzE4MDk3OCIsInN1YiI6IjEzYTUyNjUyLTY5YmEtNDI4My04OGQwLTdiZGI1MDgzR7ZhNiIsImp0aSI6ImI5MGNmMzM0LTJiMmUtNGU1MS04MWZlLTQ3MDViNTRjMTNiMiIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYXRvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMiOiI3Mjk0N2RlYi1mM2Y2LTQ4ZWEtYWE0ZC0wOTJhOWZkNzBmNDIiLCJzY29wZSI6IjIiLCJraW5kIjoiMiJ9.Sv1d9-J5uKX7-dYFCds9mdPBxC3-_glCoVciPwJZR82MLYP5lZe5Rq56KbzjmEA3BlS5wx0j7jK75ZNFgM-Y4gEZSYmlAxArrM7DvK1CPoGDib_XAWqNw2mBNUZloGe0yTh8FvVQlw2Hb8NddMmfJdCi5JRrSguRgX-Z1kojI8Zx7HVWAanG8woI_YfvBamN4_NVJRbQR10iLbYNK5_kclK9YmJC4rmC0RgO2FSXa-0gMldmAQ_7iDERBDdmHBpWRJTwZblYK40vSJYNz27cq-G9BAyQR-UqwbAYzTBenn7S99FwGzkA_W1NeyBBq5Va-nFZL7rY_h6TrfcKGRSrvA"

 "expires_in": 3600,

}

  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 in the application/x-www-form-urlencoded format:

Request:

POST https://localhost:1280/api/v3/token

 

Request Header:

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

 

Request Body:

grant_type : refresh_token

refresh_token : eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDA4MTc4IiwiZXhwIjoiMTU4MzE4MDk3OCIsInN1YiI6IjEzYTUyNjUyLTY5YmEtNDI4My04OGQwLTdiZGI1MDgzR7ZhNiIsImp0aSI6ImI5MGNmMzM0LTJiMmUtNGU1MS04MWZlLTQ3MDViNTRjMTNiMiIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYXRvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMiOiI3Mjk0N2RlYi1mM2Y2LTQ4ZWEtYWE0ZC0wOTJhOWZkNzBmNDIiLCJzY29wZSI6IjIiLCJraW5kIjoiMiJ9.Sv1d9-J5uKX7-dYFCds9mdPBxC3-_glCoVciPwJZR82MLYP5lZe5Rq56KbzjmEA3BlS5wx0j7jK75ZNFgM-Y4gEZSYmlAxArrM7DvK1CPoGDib_XAWqNw2mBNUZloGe0yTh8FvVQlw2Hb8NddMmfJdCi5JRrSguRgX-Z1kojI8Zx7HVWAanG8woI_YfvBamN4_NVJRbQR10iLbYNK5_kclK9YmJC4rmC0RgO2FSXa-0gMldmAQ_7iDERBDdmHBpWRJTwZblYK40vSJYNz27cq-G9BAyQR-UqwbAYzTBenn7S99FwGzkA_W1NeyBBq5Va-nFZL7rY_h6TrfcKGRSrvA

  1. To log out, the client sends the DELETE request to the /users/{userId}/tokens path. To inquire a value for the userId parameter, the client can send the GET request to the users/me path.

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

Request:

GET https://localhost:1280/api/v3/users/me

 

Request Header:

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDAxMDU4IiwiZXhwIjoiMTU4MzE3Mzg1OCIsInN1YiI6IjEzYTUyNjUyLTY5YmEtNDI4My04OGQwLTdiZGI1MDgzY2ZhNiIsImp0aSI6IjdjMGQ3ZWY0LWRiYWUtNDYzMS04NmJlLTc5MjEwNDgyNTZiOSIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYXRvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMi90I1YTMzNjZmMC01N2MxLTRjZTQtYWY5My0xZTExN2IyZDkzNTQiLCJzY29wZSI6IjIiLCJraW5kIjoiMiJ9.oYWUl0aLhV5gR7HypeI8-DSh3PkT_z3m937S-_fssuHKoEaq7m7h9K0M41eBe6soqz1sp5qvafvEVWKwzZuPSrHajCe8juxizaLFGK0qrh75vrpaLyERzBWRvnbaVlEKiuN_jOIgrxbz3aPHao3Ua6HsnPWjh1VxWwv7wY1NfNE_IuJ2yz1hFyiC08IMMjUBOzcoVo6vj9zzwQGWdwetLguyhWcGrnMScsR0jfKGxvDY3SLL5Z0WPY5YbWiV1z6BcAGUbyqsK9xdNCoDMej1W5ugA5-xBKbMeh_SLcY2jMnvLTsTWyyj6jkDqOTUA15MJUWAxApAc35I4T2_ZufSCQ

The server sends a response in the following format.

Response Code:

200 OK

Response Body:

{

 "data": {

   "instanceUid": "13a52652-64ba-428a-88d0-7bdb5083c5a6",

   "organizationUid": "7b5ee6218-992c-4f9b-89cc-e39eda547944",

   "userName": "vspc\\Administrator",

   "status": "enabled",

   "role": "portalAdministrator",

   "profile": {

     "firstName": "Stan",

     "lastName": "Smith",

     "title": "mr",

     "email": "s.smith@mycompany.com",

     "address": null,

     "phone": null

   },

   "credentials": {

     "userName": "vspc\\Administrator",

     "password": null

   }

 }

}

Client can use the instanceUid property value in the log out operation.

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

Request:

DELETE https://localhost:1280/api/v3/users/13a52652-64ba-428a-88d0-7bdb5083c5a6/tokens

 

Request Header:

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDAxMDU4IiwiZXhwIjoiMTU4MzE3Mzg1OCIsInN1YiI6IjEzYTUyNjUyLTY5YmEtNDI4My04OGQwLTdiZGI1MDgzY2ZhNiIsImp0aSI6IjdjMGQ3ZWY0LWRiYWUtNDYzMS04NmJlLTc5MjEwNDgyNTZiOSIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYXRvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMi90I1YTMzNjZmMC01N2MxLTRjZTQtYWY5My0xZTExN2IyZDkzNTQiLCJzY29wZSI6IjIiLCJraW5kIjoiMiJ9.oYWUl0aLhV5gR7HypeI8-DSh3PkT_z3m937S-_fssuHKoEaq7m7h9K0M41eBe6soqz1sp5qvafvEVWKwzZuPSrHajCe8juxizaLFGK0qrh75vrpaLyERzBWRvnbaVlEKiuN_jOIgrxbz3aPHao3Ua6HsnPWjh1VxWwv7wY1NfNE_IuJ2yz1hFyiC08IMMjUBOzcoVo6vj9zzwQGWdwetLguyhWcGrnMScsR0jfKGxvDY3SLL5Z0WPY5YbWiV1z6BcAGUbyqsK9xdNCoDMej1W5ugA5-xBKbMeh_SLcY2jMnvLTsTWyyj6jkDqOTUA15MJUWAxApAc35I4T2_ZufSCQ

The server sends a response in the following format.

Response body

{

"data": true

}

I want to report a typo

There is a misspelling right here:

 

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