This is an archive version of the document. To get the most up-to-date information, see the current version.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.
|
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.
|
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.
- 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:
- 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: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, } |
- 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:
- 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: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 |
- 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 } |