OAuth 2.0 Authentication
This authentication type is based on the OAuth 2.0 Authorization Framework.
To obtain a pair of tokens, send the HTTP POST request to the /token path.
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.
|
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, send the HTTP POST 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.
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 user.
To revoke a token of a specific user identity, 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.
|
Token invalidation consumes a significant amount of server resources. We recommend to use it only in case of emergency, for example, if a token is stolen. |
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, send the HTTP POST request with the application/x-www-form-urlencoded content type to the /token path.
In the body of the request, specify the following parameters:
- grant_type — the authorization process requires that the password value is 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://vspc:1280/api/v3/token
Request Header: Content-Type: application/x-www-form-urlencoded Authorization: Bearer
Request Body: grant_type : password username : vspc\administrator password : Password1 |
The server sends a response in the following format.
Response Code: 200 OK 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" "mfa_token": null, "encrypted_code": null, "expires_in": 3600, } |
After you authorize you can authenticate as another user. For details, see User Impersonation.
- To refresh a pair of tokens, send the HTTP POST request with the application/x-www-form-urlencoded content type to the /token path.
In the body of the request, specify the following values for the parameters:
- grant_type — to refresh the token, it is required that the refresh_token value is specified for this parameter.
- refresh_token — the previously saved refresh token.
Request: POST https://vspc:1280/api/v3/token
Request Header: Content-Type: application/x-www-form-urlencoded Authorization: Bearer
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 |