Requesting Authorization

In this article

    To get access to the REST API resources, the client obtains an access token — a string that denotes client's access attributes and that must be specified in all requests to the REST API.

    To get an access token, send the HTTP POST request to the /api/oauth2/token path.

    In the request body, the following parameters must be specified:

    • Grant type: password or authorization_code
    • Credentials matching the grant type

    The Veeam Backup & Replication REST API accepts the following authorization grant types:

    • Password grant type — used to get an access token by providing a user name and password.
    • Authorization code grant type — used to get an access token by providing an authorization code. To get an authorization code, send the HTTP POST request to the /api/oauth2/authorization_code path.

    Using Password Grant Type

    To obtain authorization tokens, send the HTTP POST request to the /api/oauth2/token path.

    The request body must contain the grant_type parameter with the specified password value and the user credentials of a  account created in Veeam Backup & Replication.

    A successfully completed operation returns the 200 response code. In the response body, Veeam Backup & Replication returns an access token, its expiration time (in seconds) and a refresh token. Specify the access token in headers of further requests to the Veeam Backup & Replication REST API. The refresh token must be saved locally.

    Requesting AuthorizationExample

    To obtain an access token and a refresh token, send the HTTP POST request to the /api/oauth2/token path. In the x-api-version header, specify the current revision of the Veeam Backup & Replication REST API.

    In the request body, specify the following parameters:

    • grant_type — the password value must be specified for this parameter.
    • username and password — credentials used to access the server. In this example, administrator and Password1 are used.

    Request

    POST https://enterprise01.tech.local:9419/api/oauth2/token

     

    Request Header

    x-api-version:1.0-rev1

     

    Request Body

    grant_type=password&username=administrator&password=Password1

    The server sends a response in the following format.

    Response

    200

     

    Response Body

    {

     "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTUzNzksImV4cCI6MTU4NjI1NjI3OSwiaWF0IjoxNTg2MjU1Mzc5LCJhdWQiOiJhY2Nlc3MifQ.kOCwrbf6BErst5X-ZOK5zSVH9htMN5GJpPkE1MScDM08iHrF4vPZaGGlHGZzvLu6eJmzyM-GA9zG5QAoPQcQCxzhUf4btj6JvUd1thz3BgfSfCvDh_nQUG-WQ5dAkeOL8M7sze6nlHRDJDg1b7D2Ev7BsFg41ip24drWl2wyebZVZXBOwpIsD7rbX1fJW3FHfvEMyes7h8gWruHtqc-6uJnMuA7YJc706rlXHf6wgpLJAaW2qRAwtBUpE6kib9odU58Hc2aS5QqQBwwKX6hTI3ZbBDg_B5KW6xL7rRIMbtTgdEhbDn41WMPhINS9yAFf7sKvdsofStPX31H0Mt1eOg",

     "token_type": "bearer",

     "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6ImQ5ZDhiN2RlLWIwYjUtNDc1Yi04ZTE4LTU4ZGMzMzVmOWIzNSIsInNob3J0X3Rlcm1fZXhwaXJhdGlvbiI6IkZhbHNlIiwibmJmIjoxNTg2MjU1Mzc5LCJleHAiOjE1ODc0NjQ5NzksImlhdCI6MTU4NjI1NTM3OSwiYXVkIjoicmVmcmVzaCJ9.1R2vkCTmAx28mBg21vq61SYTzZN-wCLyG8SjL3iMofuhUKeZ2oRMNlOSTqZ7v-FxvMTXMIVXBw9WRDIjxMzr182K9E26UcblcUa0Gp8o0fNeCKF_pN0WwYx77Ewzedl9bUmY5rlseOjTU-dQNp-G51mGfn4dU4pEaCxFkX9NCGuJqr4Q9NedoyGXNW6PuAm8gwQnOQjLPWmCzkpaBGZMda41osPyq1bKIL6Be7cen1StTKjiU86OzM1sjIOgG3-hZnfKW5ZyO_fLb-nLeRrOuR65f9peJE3WgVFrmWm0MAtxvPCAq99Nutek2ssI2byNzxc1-hOeD-oZrwm-725G8g",

     "expires_in": 900,

     ".issued": "2020-06-10T10:29:39",

     ".expires": "2020-06-10T10:44:39",

     "username": "administrator"

    }

    Using Authorization Code Grant Type

    To get authorization using the Authorization Code grant type, first obtain an authorization code, and then get authorization tokens.

    1. To obtain an authorization code, an authorized client sends the HTTP POST request to the /api/oauth2/authorization_code path.

    A successfully completed operation returns the 200 response code. In the response body, Veeam Backup & Replication returns an authorization code, which can be used by another client to get authorization in the Veeam Backup & Replication REST API.

    Note

    The Veeam Backup & Replication authorization code expires in 60 seconds.

    1. To obtain an access token and a refresh token, the client sends the HTTP POST request to the /api/oauth2/token path. The request body must contain the grant_type parameter with the specified authorization_code value and the authorization code itself.

    A successfully completed operation returns the 200 response code. In the response body, Veeam Backup & Replication returns an access token, its expiration time (in seconds) and a refresh token. The client must specify the access token in headers of further requests to the Veeam Backup & Replication REST API. The refresh token must be saved locally.

    Requesting AuthorizationExample

    To access the REST API using an authorization code:

    1. To obtain an authorization code, an authorized client sends the HTTP POST request to the /api/oauth2/authorization_code path. In the x-api-version header, specify the current revision of the Veeam Backup & Replication REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

    Request

    POST https://enterprise01.tech.local:9419/api/oauth2/authorization_code

     

    Request Header

    x-api-version:1.0-rev1

    Authorization:Bearer eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQi-LCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTUzNzksImV4cCI6MTU4NjI1NjI3OSwiaWF0IjoxNTg2MjU1Mzc5LCJhdWQiOiJhY2Nlc3MifQ.kOCwrbf6BErst5X-ZOK5zSVH9htMN5GJpPkE1MScDM08iHrF4vPZaGGlHGZzvLu6eJmzyM-GA9zG5QAoPQcQCxzhUf4btj6JvUd1thz3BgfSfCvDh_nQUG-WQ5dAkeOL8M7sze6nlHRDJDg1b7D2Ev7BsFg41ip24drWl2wyebZVZXBOwpIsD7rbX1fJW3FHfvEMyes7h8gWruHtqc-6uJnMuA7YJc706rlXHf6wgpLJAaW2qRAwtBUpE6kib9odU58Hc2aS5QqQBwwKX6hTI3ZbBDg_B5KW6xL7rRIMbtTgdEhbDn41WMPhINS9yAFf7sKvdsofStPX31H0Mt1eOg

    The server sends a response in the following format.

    Response

    200

     

    Response Body

    {

     "code": "AAEAAJO1R+DANfH7JDlyUzDVYGDw+77dyaa0mFu8nozvbOreW31Uu1X+mejLUilSp6nBrhcmv9/LTjAjMz3P+grbg1OATjZN7kZ5XbhenJG7DrVUtvpA6h5aDmma8INsMv6xW7+TmcOUNlK65n2J2/rQCjg80rMOSjlpnkQkX2s+tXOxkX+h/GTRSdxCulLhn69Rj+8Qvmh3+h8c3g+RVnhfSWwfxVR1+sFtViNQwQzI3hBRvxivb9IZo9WSYgtDJc8816OrUrIn26h71jYm6WfYn3ZiMp/VkABHqvqAsIMuKD1Xat9lnQyxARc1ZU9suM7Ivd5I7Ew51vMMPhXMetchrGkIAAAAWccK8uTa1wg="

    }

    1. To obtain an access token and a refresh token, send the HTTP POST request to the api/oauth2/token path. In the x-api-version header, the current revision of the Veeam Backup & Replication REST API must be specified.

    In the request body, specify the following parameters:

    • grant_type — the authorization_code value must be specified for this parameter.
    • code — the authorization code previously issued by the authorization server.

    Request

    POST https://enterprise01.tech.local:9419/api/oauth2/token

     

    Request Header

    x-api-version:1.0-rev1

     

    Request Body

    grant_type=authorization_code&code=AAEAAJO1R+DANfH7JDlyUzDVYGDw+77dyaa0mFu8nozvbOreW31Uu1X+mejLUilSp6nBrhcmv9/LTjAjMz3P+grbg1OATjZN7kZ5XbhenJG7DrVUtvpA6h5aDmma8INsMv6xW7+TmcOUNlK65n2J2/rQCjg80rMOSjlpnkQkX2s+tXOxkX+h/GTRSdxCulLhn69Rj+8Qvmh3+h8c3g+RVnhfSWwfxVR1+sFtViNQwQzI3hBRvxivb9IZo9WSYgtDJc8816OrUrIn26h71jYm6WfYn3ZiMp/VkABHqvqAsIMuKD1Xat9lnQyxARc1ZU9suM7Ivd5I7Ew51vMMPhXMetchrGkIAAAAWccK8uTa1wg=

    The server sends a response in the following format.

    Response

    200

     

    Response Body

    {

     "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNjQxNjAsImV4cCI6MTU4NjI2NTA2MCwiaWF0IjoxNTg2MjY0MTYwLCJhdWQiOiJhY2Nlc3MifQ.TbUBFfPcZ1qYARjCindWw3GK-aVtScd5Aej-AuaYGf833EPZtQYj0wI5VI6Nk2vl8ekaUKcAKE-RgAgi3qPjlscBoIXaptgJOVMCZgbVaacLEkiPANvsHh9ZZYtQnIzA9NrAXnnBlGxvxWae2n_YlySTiywYIyy-PSscHg7v4K-QOlYYKcUBSub3wnKSHcAlFN_JsU20YmDh0fOUsgpzFQZBLf9uNBdubgCpejywGrMYLHoTDZpDvERelwLw_y-hsrWoHTbVfnExkHBzpV0zX3Hc_I-hHiikykRrafx2UWfdD3RNqb7Qx6XnwKJz7TfkWS9XnWv5zDAK23V1KjWp0g",

     "token_type": "bearer",

     "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6IjQwZTA4ZmJmLTIwYjYtNGM2NS05YjQ4LWQzZTM4NTk5OTBmMCIsInNob3J0X3Rlcm1fZXhwaXJhdGlvbiI6IkZhbHNlIiwibmJmIjoxNTg2MjY0MTYwLCJleHAiOjE1ODc0NzM3NjAsImlhdCI6MTU4NjI2NDE2MCwiYXVkIjoicmVmcmVzaCJ9.ilRxFQN9NGxbBlIuJGseZf3Y_5L_wTAJIv13LdJ0-neP9jmWB5_ar9tvlcOxCafVA1xpZgZLRjwqyOklTEAt6YgxFXzzT4Sjgl347x3YuYLneQfs-yTdbs3ifGGnLWFArxcXqkDRf4jDItULIfBSSk47hZ9xYVIniDQw7wxZ_nBoQbx4Grrxb1BRFCtcMBXBVN6AfDK3-57a0_m8UyeeJMop9m946hznU6pvIl8d1ZJdgPVo6ZJzW36qHdMxr-Gq086CS5BT4NOMrRiYw1tS8rxA9q58eMDHvK1HlzkqBxEusqdPDNx3riB2FRJOn9fQGY_l7DACD2c-Y0pTGI2NCA",

     "expires_in": 900,

     ".issued": "2020-04-07T12:56:00",

     ".expires": "2020-04-07T13:11:00"

    }