User Name and Password Authentication
To authenticate with user name and password, send the HTTP POST request to the /authentication/usernamepassword path.
A successfully completed operation returns the 200 OK response code and an access token in the response body. Inserts the access token in headers of further requests to the Veeam Service Provider Console REST 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, send the HTTP POST 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.
Token Invalidation
An access token expires in 1 hour which means that the access to resources is disabled automatically. If an access token must be revoked immediately, send the HTTP DELETE request to the /users/{userId}/tokens path where {userId} is a UID assigned to a client user. The same way you can log out another user by providing UID assigned to this user as the path parameter.
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 you communicate with the server 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://vspc:1280/api/v3/authentication/usernamepassword
Request Header: Content-Type: multipart/form-data Authorization: Bearer
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 HTTP 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://vspc: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, send the HTTP DELETE request to the /users/{userUid}/tokens path. To inquire a value for the userUid parameter, send the HTTP 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://vspc: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 } } } |
Provide the instanceUid property value as the userUid parameter of the logout request.
In the Authorization header, specify currently valid access token in the Bearer <access_token> format.
Request: DELETE https://vspc: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 } |