User Name and Password Authentication
To authenticate with user name and password, the client sends the POST HTTPS request to the /authentication/usernamepassword 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 token in the response body. The client inserts the access token in headers of further requests to Veeam Service Provider Console RESTful API.
|
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. |
Updating Access Token
To obtain a new access token in case the current one expires or becomes invalid, the client sends the POST HTTPS request to the /authentication/refresh path. A successfully completed operation returns the 200 OK response code and a new access token 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 where {userId} is a UID assigned to a client user. The same way a client with sufficient permissions can log out another user by providing UID assigned to this user in the path.
To log out a specific user identity, a client can specify ID assigned to this user identity in the userLoginID query parameter.
A successfully completed operation returns the 200 OK response code and the true value 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 in the multipart/form-data format to the /authentication/usernamepassword path.
In the body of the request, the client specifies 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/authentication/usernamepassword
Request Header: Content-Type: multipart/form-data
Request Body: username : vspc\administrator password : Password1 |
The server sends a response in the following format.
Response Code: 200 OK Response Body: { "data": [ { "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDAxMDU4IiwiZXhwIjoiMTU4MzAwNDY1OCIsInN1YiI6IjEzYTUyNjUyLTY5YmEtNDI4My04OGQwLTdiZGI1MDgzY2ZhNiIsImp0aSI6Ijg1MzA4YjAzLWMzOGMtNDMwYi05MGY1LTY3MWY2YzJlOWIwNiIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYTFvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMiOiI1YTMzNjZmMC01N5MxLTRjZTQtYWY5My0xZTExN2IyZDkzNTQiLCJzY29wZSI6IjIiLCJraW5kIjoiMyJ9.fkiV37L-Cpg9hTWigvz4KwxqnxIGRs58tre42OZeVvALMy-3A2xU_xfNwt489__f0adCoq5IIG28RKlGOU_aySHtvb1fM1-Xq45jni23xrZvPHK_qC0v_nq-q6Xqi0z_wBkmi8E63G7_BquzCnKlsWVjJol0miYlu9xxHsDagFjgVFLgd6k7iQHP4kbew-v5BGg2DjEpfn1WnNaWF5sCHoHHtIYLPHm0IBh1KQtgMVL1k_C33L33DBMVFyyYHu-_cGwgaOUnefj2BFu0ci8dxhjU81vfcDqraMZ61gh5QH9Xd8DrYmf2Yh0u4XhDn3zDSo7CjR4vgUiS984aP6S-Rw", "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDAxMDU4IiwiZXhwIjoiMTU4MzE3Mzg1OCIsInN1YiI6IjEzYTUyNjUyLTY5YmEtNDI4My04OGQwLTdiZGI1MDgzY2ZhNiIsImp0aSI6IjdjMGQ3ZWY0LWRiYWUtNDYzMS04NmJlLTc5MjEwNDgyNTZiOSIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYXRvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMi90I1YTMzNjZmMC01N2MxLTRjZTQtYWY5My0xZTExN2IyZDkzNTQiLCJzY29wZSI6IjIiLCJraW5kIjoiMiJ9.oYWUl0aLhV5gR7HypeI8-DSh3PkT_z3m937S-_fssuHKoEaq7m7h9K0M41eBe6soqz1sp5qvafvEVWKwzZuPSrHajCe8juxizaLFGK0qrh75vrpaLyERzBWRvnbaVlEKiuN_jOIgrxbz3aPHao3Ua6HsnPWjh1VxWwv7wY1NfNE_IuJ2yz1hFyiC08IMMjUBOzcoVo6vj9zzwQGWdwetLguyhWcGrnMScsR0jfKGxvDY3SLL5Z0WPY5YbWiV1z6BcAGUbyqsK9xdNCoDMej1W5ugA5-xBKbMeh_SLcY2jMnvLTsTWyyj6jkDqOTUA15MJUWAxApAc35I4T2_ZufSCQ", "username": "vspc\\Administrator", "origin": "Localhost", "expirationTime": "2020-03-10T22:30:57.7329569+03:00" } ] } |
- To refresh a pair of tokens, the client sends the POST request to the authentication/refresh path in the multipart/form-data format.
In the request body, the client specifies the refresh token.
Request: POST https://localhost:1280/api/v3/authentication/refresh
Request Header: Content-Type: multipart/form-data
Request Body: refreshToken : eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOiIxNTgzMDAxMDU4IiwiZXhwIjoiMTU4MzE3Mzg1OCIsInN1YiI6IjEzYTUyNjUyLTY5YmEtNDI4My04OGQwLTdiZGI1MDgzY2ZhNiIsImp0aSI6IjdjMGQ3ZWY0LWRiYWUtNDYzMS04NmJlLTc5MjEwNDgyNTZiOSIsIm5hbWUiOiJYQUc0M1xcQWRtaW5pc3RyYXRvciIsImxpZCI6IjgiLCJ1aWQiOiI3IiwidHMi90I1YTMzNjZmMC01N2MxLTRjZTQtYWY5My0xZTExN2IyZDkzNTQiLCJzY29wZSI6IjIiLCJraW5kIjoiMiJ9.oYWUl0aLhV5gR7HypeI8-DSh3PkT_z3m937S-_fssuHKoEaq7m7h9K0M41eBe6soqz1sp5qvafvEVWKwzZuPSrHajCe8juxizaLFGK0qrh75vrpaLyERzBWRvnbaVlEKiuN_jOIgrxbz3aPHao3Ua6HsnPWjh1VxWwv7wY1NfNE_IuJ2yz1hFyiC08IMMjUBOzcoVo6vj9zzwQGWdwetLguyhWcGrnMScsR0jfKGxvDY3SLL5Z0WPY5YbWiV1z6BcAGUbyqsK9xdNCoDMej1W5ugA5-xBKbMeh_SLcY2jMnvLTsTWyyj6jkDqOTUA15MJUWAxApAc35I4T2_ZufSCQ |
- 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 } |
