OAuth 2.0 Authentication

In this article

    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.

    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, 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.

    OAuth 2.0 Authentication Note:

    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.

    1. To obtain an access and a refresh token, send the HTTP POST request with the multipart\form-data content type to the /token path.

    In the body of the request, the specify the following parameters:

    Request:

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

     

    Request Header:

    Content-Type: multipart/form-data

    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.

    1. To refresh a pair of tokens, send the HTTP POST request with the multipart\form-data 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: multipart\form-data

    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