Veeam Backup for Microsoft Azure 8
REST API Reference
Related documents

Overview

The following topics will instruct you how to connect to the REST API and authorize your access, and how to control and sort the data that the REST API returns.

Resource URLs

Each Veeam Backup for Microsoft Azure REST API-exposed entity has a resource representing it. To get a resource representation, request its URL.

Veeam Backup for Microsoft Azure REST API Resource URLs

All Veeam Backup for Microsoft Azure REST API v8 requests use the following base URL format:

https://<hostname>/api/<version>

where:

  • <hostname> is a public IPv4 address or DNS hostname of the Azure VM running Veeam Backup for Microsoft Azure.

  • <version> is an API version.

    The current version is v8.

To get a collection of Veeam Backup for Microsoft Azure REST API resources, request a base URL followed by a resource collection endpoint.

https://51.11.247.127/api/v8/accounts/standard

To get a representation of an individual resource, enter a resource identifier after the resource collection endpoint.

https://51.11.247.127/api/v8/accounts/standard/543

The resource identifier is represented by the id property of the resource from the collection.

[
  {
    "name": "SMTP Account",
    "id": "543",
    ...
  }
]

Configuration Restore REST API Resource URLs

All Configuration Restore REST API v8 requests use the following base URL format:

https://<hostname>/api/restoreservice/<version>

where:

  • <hostname> is a public IPv4 address or DNS hostname of the Azure VM running Veeam Backup for Microsoft Azure.

  • <version> is an API version.

    The current version is v8.

Versioning

The Veeam Backup for Microsoft Azure REST API is available in multiple versions. The Veeam Backup for Microsoft Azure REST API is backward-compatible with client applications that were created using earlier versions of the REST API specification. This means that you can use any of the supported REST API specifications to perform operations with Veeam Backup for Microsoft Azure resources if the specification version has been released earlier or with the product version installed on the backup appliance:

Veeam Backup for Microsoft Azure 7.0

Veeam Backup for Microsoft Azure 6.0

Veeam Backup for Microsoft Azure 5a

Veeam Backup for Microsoft Azure 5.0

Veeam Backup for Microsoft Azure 4.0

Veeam Backup for Microsoft Azure 3.0

Veeam Backup for Microsoft Azure 2.0

v2

Authorization and Security

To start working with the Veeam Backup for Microsoft Azure REST API, users must first authenticate themselves and get authorization to make requests. Veeam Backup for Microsoft Azure REST API authorization process is based on the OAuth 2.0 Authorization Framework and involves obtaining an access token and a refresh token.

  • Access token is a string that represents authorization issued to the client and that must be used in all requests during the current logon session. By default, the Veeam Backup for Microsoft Azure access token expires in 60 minutes.
  • Refresh token is a string that represents authorization granted to the client and that can be used to obtain a new access token if the current access token expires or becomes lost. By default, refresh token expires in 14 days. If you want to change the expiration period to 15 minutes, set the short_lived_refresh_token parameter value to true.

For increased security, Veeam Backup for Microsoft Azure allows you to use multi-factor authentication (MFA) to verify user identity. It is recommended to enable MFA for Veeam Backup for Microsoft Azure users. For more information, see Multi-Factor Authentication or the Veeam Backup for Microsoft Azure User Guide, section Managing User Accounts.

Authorization in REST API

Veeam Backup for Microsoft Azure follows OAuth 2.0 protocol for authenticating and authorizing users in the REST API. The authorization process involves the following procedures:

  1. Requesting authorization.
  2. Using the refresh token.
  3. Performing logout.

Requesting Authorization

The Veeam Backup for Microsoft Azure REST API accepts several grant types to authenticate a Veeam Backup for Microsoft Azure user:

You can configure single sign-on (SSO) settings in Veeam Backup for Microsoft Azure and retrieve user identities from your identity provider. To authenticate a user retrieved from the identity provider, the Veeam Backup for Microsoft Azure REST API uses single sign-on authorization. For more information on configuring SSO settings, see the Configuring SSO Settings section of the Veeam Backup for Microsoft Azure User Guide.

Using Password Grant Type

To obtain authorization tokens, a user sends the HTTP POST request to the /oauth2/token endpoint.

The request body must contain the grant_type parameter with the specified Password value and the credentials of a user created in Veeam Backup for Microsoft Azure. For more information on how to create users, see Users or the Veeam Backup for Microsoft Azure, section Managing User Accounts.

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

To learn how to authorize your access using the Password grant type, see Example [Password]. Alternatively, you can use the Swagger UI.

Using MFA Grant Type

NOTE

MFA is disabled by default. To learn how to enable MFA, see Multi-Factor Authentication or the Veeam Backup for Microsoft Azure User Guide, section Enabling Multi-Factor Authentication.

If multi-factor authentication (MFA) is enabled for a user, the user must first obtain an mfa token, and then get authorization tokens.

  1. To obtain an mfa token, the user sends the HTTP POST request to the /oauth2/token endpoint. The request body must contain the grant_type parameter with the specified Password value and the credentials of the user.

    A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Microsoft Azure returns an mfa token.

  2. To obtain an access token and a refresh token, the user must send another HTTP POST request to the /v8/token endpoint. The request body must contain the grant_type parameter with the specified Mfa value, the mfa token previously received from the authorization server, and the verification code generated by an authentication application on the trusted device.

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

To learn how to authorize your access using the MFA grant type, see Example [MFA]. Alternatively, you can use the Swagger UI.

Example [Password]

To obtain an access token and a refresh token, a user sends the HTTP POST request to the api/oauth2/token endpoint.

In the request body, the user specifies 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://51.11.247.127/api/oauth2/token
Request Header:
Content-Type: application/x-www-form-urlencoded

Request Body:
Username=administrator&Password=Password1&grant_type=Password

The server sends a response in the following format.

Response:
200

Response Body:
{
   "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjUxOUMwRDlFMkRCRTcxQ0E5RkJBOTU3QkJBNENGNEJGMjBCMkM2QzMiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiIwY2QyMDU3Ni05MzEwLTQ5NGYtOGM4ZS01OWEwZjRmMDc1MmMiLCJuYW1laWQiOiI2ZjQyMzZjMi0xNjI2LTRjZmItOGVlYy00OTYxZTU3YTAyNDEiLCJ1bmlxdWVfbmFtZSI6ImFsZW5rYSIsInJvbGUiOiJQb3J0YWxBZG1pbiIsIm5iZiI6MTYzMzM1OTQ1OCwiZX...",
   "token_type": "bearer",
   "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjUxOUMwRDlFMkRCRTcxQ0E5RkJBOTU3QkJBNENGNEJGMjBCMkM2QzMiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiIwY2QyMDU3Ni05MzEwLTQ5NGYtOGM4ZS01OWEwZjRmMDc1MmMiLCJuYW1laWQiOiI2ZjQyMzZjMi0xNjI2LTRjZmItOGVlYy00OTYxZTU3YTAyNDEiLCJ1bmlxdWVfbmFtZSI6ImFsZW5rYSIsInJvbGUiOiJQb3J0YWxBZG1pbiIsIm5iZiI6MTYzMzM1OTQ1OCwiZXh...",
   "expires_in": 3600,
   ".issued": "2021-10-04T14:57:38.1832163Z",
   ".expires": "2021-10-04T15:57:38.1791726Z",
   "userId": "6f6356c2-1626-4cfb-8eec-4961e57a0241",
   "username": "administrator",
   "roleName": "PortalAdmin",
   "userType": "Internal",
   "latestNewsShown": true,
   "mfa_enabled": false,
   "shortLived": false
}

Example [MFA]

To access the REST API when MFA is enabled, a user must do the following:

  1. To obtain an mfa token, the user sends the HTTP POST request to the /oauth2/token endpoint.

    In the request body, the user specifies 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://51.11.247.127/api/oauth2/token

Request Body:
Username=administrator&Password=Password1&grant_type=Password

    The server sends a response in the following format.

    Response:
200

Response Body:
{
   "token_type": "bearer",
   "expires_in": 0,
   ".issued": "0001-01-01T00:00:00Z",
   ".expires": "0001-01-01T00:00:00Z",
   "userId": "d5022b05-574f-494e-9414-797834d5d411",
   "username": "administrator",
   "roleName": "PortalOperator",
   "userType": "Internal",
   "latestNewsShown": true,
   "mfa_enabled": true,
   "mfa_token": "MDhDQjQ4RENDNEU1QzA1ODFFMTQxRUE0QTZGQTUyMzFDQzczMUQxRDFEREZGMzI1N0NFMjQxNzFFODRERjUxOQ==",
   "shortLived": false
}

  2. To obtain an access token and a refresh token, the user sends the HTTP POST request to the /oauth2/token endpoint.

    In the request body, the user specifies the following parameters:

    • grant_type — the Mfa value must be specified for this parameter.
    • mfa_token — the mfa token previously received from the authorization server.
    • mfa_code — the six-digit verification code generated on the trusted device.
    Request:
POST https://51.11.247.127/api/oauth2/token

Request Body:
grant_type=Mfa&mfa_token=NkZFMzc4RjA4NzJCQzk1QjU3NTY1Mzc2RTU1MjVCODkzOThDQjdGODMzNDVDMEY0QUZGRTIzMjZFQTNDQ0QxRg==&mfa_code=346816

    The server sends a response in the following format.

    Response:
200

Response Body:
{
   "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjUxOUMwRDlFMkRCRTcxQ0E5RkJBOTU3QkJBNENGNEJGMjBCMkM2QzMiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiJmZTRhYjc1Yi1lOGNlLTQ2OTEtODFlNC02OGRhYzI2ZDZlODEiLCJuYW1laWQiOiJkNTAyMmIwNS01NzRmLTQ5NGUtOTQxNC03OTc4MzRkNWQ0MTEiLCJ1bmlxdWVfbmFtZSI6InBvcnRhbCIsInJvbGUiOiJQb3J0YWxPcGVyYXRvciIsIm5iZiI6MTYzMzM1OTcyNiwiZXhwIjoxNjMzMzYzMzI2LCJpYXQiOjE2MzMzNTk3MjYsImF1ZCI6ImFwaS9kZWZhdWx0LzVkMDRjMTc4LWVkYWI...",
   "token_type": "bearer",
   "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjUxOUMwRDlFMkRCRTcxQ0E5RkJBOTU3QkJBNENGNEJGMjBCMkM2QzMiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiJmZTRhYjc1Yi1lOGNlLTQ2OTEtODFlNC02OGRhYzI2ZDZlODEiLCJuYW1laWQiOiJkNTAyMmIwNS01NzRmLTQ5NGUtOTQxNC03OTc4MzRkNWQ0MTEiLCJ1bmlxdWVfbmFtZSI6InBvcnRhbCIsInJvbGUiOiJQb3J0YWxPcGVyYXRvciIsIm5iZiI6MTYzMzM1OTcyNiwiZXhwIjoxNjM0NTY5MzI2LCJpYXQiOjE2MzMzNTk3MjYsImF1ZCI6ImF1dGgvcmVmcmVzaC85YTA0OWRmNi02ZWUS...",
   "expires_in": 3600,
   ".issued": "2021-10-04T15:02:06.8846099Z",
   ".expires": "2021-10-04T16:02:06.8802955Z",
   "userId": "d5022b05-574f-494e-9414-797834d5d411",
   "username": "administrator",
   "roleName": "PortalOperator",
   "userType": "Internal",
   "latestNewsShown": true,
   "mfa_enabled": false,
   "shortLived": false
}

Using Refresh Token

To obtain a new pair of tokens in case the access token expires or becomes lost, a user sends the HTTP POST request with the refresh token in the request body to the /oauth2/token endpoint. A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.

TIP

If you lose the refresh token, you can log in again under the same user account and get a new pair of tokens.

Example

To obtain an access token and a refresh token, a user sends the HTTP POST request to the /oauth2/token endpoint.

In the body of the request, the user specifies the following parameters:

  • grant_type — to refresh the token, it is required that the Refresh_token value must be specified for this parameter.
  • refresh_token — the previously saved refresh token.
Request:
POST https://51.11.247.127/api/oauth2/token

Request Body:
"Username=administrator&Password=Password&refresh_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkEyNzE5ODUzM0E0MTQyODNCNjMxRjEzRTczMTg4QTRFMDMyREU1QzAiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiIwNzFlYzJkZS03ZDY4LTRkNGEtYjIwZC0yM2Y5MmVjZjAwYmMiLCJ1bmlxdWVfbmFtZSI6IkFkbWluIiwicm9sZSI6IkFkbWluaXN0cmF0b3IiLCJuYmY..."

The server sends a response in the following format.

Response:
200

Response Body:
{
   "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjUxOUMwRDlFMkRCRTcxQ0E5RkJBOTU3QkJBNENGNEJGMjBCMkM2QzMiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiIzZGE0ZmQzNC03MTY2LTQ2Y2ItOTkxYS01MWE4ZGIxMDVlMjQiLCJuYW1laWQiOiI2ZjQyMzZjMi0xNjI2LTRjZmItOGVlYy00OTYxZTU3YTAyNDEiLCJ1bmlxdWVfbmFtZSI6ImFsZW5rYSIsInJvbGUiOiJQb3J0YWxBZG1pbiIsIm5iZiI6MTYzMzM1OTg0NCwiZXhwIjoxNjMzMzYzNDQ0LCJpYXQiOjE2MzMzNTk4NDQsImF1ZCI6ImFwaS9kZWZhdWx0LzVkMDRjMTc4LWVkYWItNDY0ZS1iNWI3LWRiOTZmOWM5YTk5YiJ9.2WoK8a8iBoF2GFhvpLwrdhOQaWgvYQi-hdWU4Vqn7qtogBrUvbPlswn9QWMBh7Fpmi4GJfQxhiAjHeralXNpF1sLr-43vONApxSTOFbZP0uWEoM1fP36DgDssi2YkD6UAn4eWRrgcqthTSgEteB0QMhqIknT7yfaMMvhLXsvSFLl31DB4nY0T8iPb7rLSXvgQ6VGUe0VYHUqbDRTg2gE0nOAMsJvP8Sy27HO-v2BKBHXJRR_N08AM04RWtnzn1Ttdepv353lT90lrMXBY440TvC4Lu9nCMxXY4Ji6o-8TX1BRSSYazOnV6pHtVrueQ-wfBU6CKHE5a2VcSif_ncDLA",
   "token_type": "bearer",
   "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjUxOUMwRDlFMkRCRTcxQ0E5RkJBOTU3QkJBNENGNEJGMjBCMkM2QzMiLCJ0eXAiOiJKV1QifQ.eyJqdGkiOiIzZGE0ZmQzNC03MTY2LTQ2Y2ItOTkxYS01MWE4ZGIxMDVlMjQiLCJuYW1laWQiOiI2ZjQyMzZjMi0xNjI2LTRjZmItOGVlYy00OTYxZTU3YTAyNDEiLCJ1bmlxdWVfbmFtZSI6ImFsZW5rYSIsInJvbGUiOiJQb3J0YWxBZG1pbiIsIm5iZiI6MTYzMzM1OTg0NCwiZXhwIjoxNjM0NTY5NDQ0LCJpYXQiOjE2MzMzNTk4NDQsImF1ZCI6ImF1dGgvcmVmcmVzaC85YTA0OWRmNi02ZWUxLTRjYzktOThiNy0wZWZkMDA1NjYwN2QifQ.1vgauZwVObWjuQgmARaVJs2OL-8ff-oY-OCatgsLrpFkiZq9ki540RWrmr0cZhFRX_zhDQXsccBETUc1OyKVMPFO-_a0SaCm9UoYE3qe0pySLdc6PySvDhh5A98IO0B-Dq_Kbs3urKEkGUFhNtEiVlr9T4Dnxlmdrc41XhmlzykQj7_gSXqm2hMv3dqF6fYTn-7kVsHP2Hxn9SimFlFHy5Shl-9o_gJySXSAca9WYr4r5kCQJojg8WEJdGy9bpuNK3XKDSe_RmmB8mJm0iJXShpZWoMUi2U2YRowWf4s9h4qs4JbsZLb7pEoSsQpNPKD_Fux37mOYhu2duX36NRC6Q",
   "expires_in": 3600,
   ".issued": "2021-10-04T15:04:04.9299072Z",
   ".expires": "2021-10-04T16:04:04.9259046Z",
   "userId": "6f4236c2-1626-4cfb-8eec-4961e57a0241",
   "username": "administrator",
   "roleName": "PortalAdmin",
   "userType": "Internal",
   "latestNewsShown": true,
   "mfa_enabled": false,
   "shortLived": false
}

Performing Logout

To log out, a user sends the HTTP DELETE request to the /oauth2/token endpoint. A successfully completed operation returns the 204 response code.

Example

To log out, a user sends the HTTP DELETE request to the /oauth2/token endpoint, and specifies currently valid access token in the Bearer <access_token> format in the Authorization header.

Request:
DELETE https://51.11.247.127/api/oauth2/token

Request Header:
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrLa1Lm41LsjpMiiPZytkqIUUiphhlXn7Vm10xlTzQUe0TU3HmXK-KD2MiB6qBImaISkEjgCmyIsurSN2mHi1Qo...

The server sends a response in the following format.

Response:
204

Multi-Factor Authentication

Veeam Backup for Microsoft Azure multi-factor authentication (MFA) is based on the Time-based One-Time Password (TOTP) method. This method requires a user to install an application authentication on the trusted device. The authenticator application will generate temporary six-digit codes used to verify the user identity. Veeam Backup for Microsoft Azure supports Google Authenticator.

You can enable or disable MFA for a Veeam Backup for Microsoft Azure user using the REST API.

Enabling MFA

To enable MFA for a specific user, do the following:

  1. To obtain a secret key and a token, send the HTTP POST request to the /users/{id}/enableMfa endpoint.

    In the request body, specify the recreate parameter. The parameter indicates whether you want to re-create the existing MFA secret key (true) or to enable MFA for the user (false). Specify the false value for the parameter.

    Request:
POST https://51.11.247.127/api/v8/users/1423/enableMfa

Request Header:
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ...

Request Body:
{
   "recreate": "false"
}

    A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Microsoft Azure returns the secret key, token, recovery scratch codes and the qrString link. The recovery codes must be saved locally.

    Response:
200

Response Body:
{
   "userId": "administrator",
   "qrString": "otpauth://totp/administrator&40ip-172-31-71-115?secret=5XKNCVA54BPWQWCXLJZYLMIBD4&issuer=ip-172-31-71-115",
   "secretKey": "5XKNCVA54BPWQWCXLJZYLMIBD4",
   "scratchCodes": [
      "79529234",
      "99447341",
      "98474119",
      "94074142",
      "95269008"
   ],
   "token": "M0Q1OEMwOEQ5MTRFNzMwMzE5MTkzMUU5MDVCNjNENzREMTQ0MDYyRUJFNEE0QjI5MzEzNzVEMUE1QURFNzBENA=="
}

  2. Install Google Authenticator on the trusted device.

  3. Open Google Authenticator, create an account and enter the secret key manually.

    Google Authenticator will generate a six-digit verification code.

    TIP

    You can use a QR code to create an account in the authentication application:

    1. On another device, open a QR code generator in a web browser.

    2. In the QR code generator, insert the qrString link returned by Veeam Backup for Microsoft Azure. The QR code generator will display a QR code.

    3. On your trusted device, open Google Authenticator and choose the Scan barcode option.

    4. Scan the displayed QR code using the device camera.

      Google Authenticator will automatically create an account and generate a six-digit verification code.

  4. To associate the authentication application with the authorization server, send the HTTP POST request to the /users/{id}/acceptMfa endpoint.

    In the Authorization header — currently valid access token in the Bearer <access_token> format.

    In the request body, specify the following parameters:

    • code — the six-digit verification code generated by the authentication application on the trusted device.
    • token — the token previously received from the authorization server.
    Request:
POST https://51.11.247.127/api/v8/users/1423/acceptMfa

Request Header:
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTv...

Request Body:
{
   "code": "475112",
   "token": "M0Q1OEMwOEQ5MTRFNzMwMzE5MTkzMUU5MDVCNjNENzREMTQ0MDYyRUJFNEE0QjI5MzEzNzVEMUE1QURFNzBENA=="
}

    A successfully completed operation returns the 204 response code.

    Response:
204
    NOTE

    In case of losing access to the authentication application:

    • To get authorization in Veeam Backup for Microsoft Azure, the user can use a recovery scratch code saved locally instead of a verification code. Each recovery code can be used only once.
    • To re-create the MFA secret key for a new device if the trusted device is lost or broken, repeat step 1 (specify the true value for the recreate parameter), and then repeat steps 2, 3 and 4.

Disabling MFA

To disable MFA for a specific user, send the HTTP POST request to the /users/{id}/disableMfa endpoint.

In the Authorization header specify the currently valid access token in the Bearer <access_token> format.

Request:
POST https://51.11.247.127/api/v8/users/1423/disableMfa

Request Header:
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrL...

A successfully completed operation returns the 204 response code.

Response:
204

The Veeam Backup for Microsoft Azure REST API has the following default security settings:

  • Access token lifetime is 1 hour (3600 seconds).
  • Refresh token lifetime is 2 hours.
  • Authorization code lifetime is 60 seconds.
  • REST API port number is 11005.

However, you can change token and authorization code lifetime defaults and the REST API port number to meet the necessary security requirements.

  1. Connect to the EC2 instance where Veeam Backup for Microsoft Azure is installed. To do that, run the following ssh command in a terminal window:

    ssh -i /path/EC2_instance.pem key ubuntu@<Public DNS hostname or IPv4 address of the EC2 instance>

  2. To change token and authorization code lifetime defaults:

    1. Create an override file.
    sudo systemctl edit veeamawsbackuprestfulapi.service
    1. Add the following variables to the file and set their values.
    [Service]
Environment=VEEAM_ACCESS_TOKEN_LIFETIME_SEC=<value>
Environment=VEEAM_REFRESH_TOKEN_LIFETIME_DAYS=<value>
Environment=VEEAM_AUTHORIZATION_CODE_LIFETIME_SECONDS=<value>

    1. Save the changes.

    2. Restart the veeamawsbackuprestfulapi service to apply the changes.

    sudo systemctl daemon-reload
sudo systemctl restart veeamawsbackuprestfulapi.service

  3. To change the REST API port number, do the following:

    1. Open the veeam-backup-publicapi-port configuration file.
    sudo nano /etc/nginx/sites-available/veeam-backup-publicapi-port.conf
    1. Set the new port number.
    listen <port_number> ssl;

    1. Save the changes.

    2. Restart the nginx service to apply the changes.

    sudo service nginx restart

HTTP Methods

To perform operations with Veeam Backup for Microsoft Azure entities using the REST API, you can use the following standard HTTP methods:

  • GET — retrieves information about a resource or collection.
  • POST — creates a new resource in a collection or activates a resource action.
  • PUT — makes changes to a resource.
  • DELETE — removes a resource from a collection.

Query Parameters

To control the amount and order of data that the Veeam Backup for Microsoft Azure REST API returns for a resource or collection, you can use the following query parameters:

IMPORTANT

All query parameters are case-sensitive.

Query parameters are part of a URL. The question mark ? separates query parameters from a resource collection endpoint.

Offset Parameter

The Offset query parameter is used to exclude from a response the first N items of a resource collection.

For example, to return a list of Azure regions starting from the third one in the /regions collection, send the following request:

GET https://<hostname>/api/<version>/cloudInfrastructure/regions?Offset=2

You can combine the Limit and the Offset query parameters to request a particular set of items. Note that the Offset parameter is applied before the Limit parameter, regardless of the parameter position in the request. That is, top results are selected from a collection where a set of items is already excluded.

The Veeam Backup for Microsoft Azure REST API returns resources in the default order based on its own semantics. To filter a collection before excluding results, use the Filter or SearchPattern or one of the filter query parameters. Note that the SearchPattern and filter parameters are applied before the Offset parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are excluded.

Limit Parameter

The Limit query parameter is used to specify the maximum number of items of a resource collection to return in a response.

For example, to return only the first 3 Azure VMs in the /virtualMachines collection, send the following request:

GET https://<hostname>/api/<version>/virtualMachines?Limit=3

The Veeam Backup for Microsoft Azure REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use the SearchPattern or one of the filter query parameters. Note that the Sort, SearchPattern and filter parameters are applied before the Limit parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are selected.

SearchPattern Parameter

The SearchPattern query parameter is used to return only those items of a resource collection whose names match the specified search pattern in the parameter value.

For example, to get only Azure VMs whose name contains the ubuntu search pattern in the /virtualMachines collection, send the following request:

GET https://<hostname>/api/<version>/virtualMachines?SearchPattern=ubuntu

Filter Parameters

Some resource properties of Veeam Backup for Microsoft Azure REST API schemas can be used as filter query parameters. Filter query parameters are used to filter items of a resource collection to return a subset of resources in a response. The subset includes only those resources that satisfy parameter value specified in the query.

For example, to return a list of protected Azure VMs of the /virtualMachines collection, send the Protected value of the ProtectionStatus filter parameter in the following request:

GET https://<hostname>/api/<version>/virtualMachines?ProtectionStatus=Protected

Pagination

To increase readability and optimize network traffic, Veeam Backup for Microsoft Azure REST API applies pagination to a number of responses that contain array of values.

Pagination data is returned in the meta section of a response and includes the following properties:

  • offset — number of resources skipped. You can skip resources using the $offset parameter.
  • limit — number of resources on the current page. The default value is 100. You can modify this number using the $limit parameter.
  • totalCount — total number of resources returned.
NOTE

Veeam Backup for Microsoft Azure REST API returns resources in the default order based on its own semantics.

Evaluation with Swagger UI

To start working with the Veeam Backup for Microsoft Azure REST API, you can use any client application that supports the HTTPS protocol.

The Veeam Backup for Microsoft Azure REST API is additionally available through the Swagger UI, a tool that you can use to evaluate and explore capabilities of the REST API. The Swagger UI visually presents API specification files and allows you to work with resources.

All resources and methods are expandable. When you expand a method, you get a full description of available parameters and an automatically generated example. You can also send requests and see response messages.

  • To access the Swagger UI for the Veeam Backup for Microsoft Azure REST API, in a web browser, navigate to the following URL:

    https://<hostname>/swagger/index.html

  • To access the Swagger UI for the Configuration Restore REST API, in a web browser, navigate to the following URL:

    https://<hostname>/restoreservice/swagger/index.html

where <hostname> is a public IPv4 address or DNS hostname of the Azure VM where Veeam Backup for Microsoft Azure is running.

In the Select a definition field, select the version of the Veeam Backup for Microsoft Azure REST API.

Viewing Swagger UI

Authorization with Swagger UI

REST API authorization with the Swagger UI involves the following procedures:

  1. Obtain an access token and a refresh token:

    1. On the Veeam Backup for Microsoft Azure API page, expand the Login resource and click POST api/oauth2/token.

    2. In the expanded method window, click Try it out.

    3. From the grant_type drop-down list, select Password.

    4. In the Username and Password fields, specify the credentials of a user created in Veeam Backup for Microsoft Azure.

    5. Click Execute.

      Requesting Authorization Tokens

      Wait for the response from the server. A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Microsoft Azure returns an access token, its expiration time and a refresh token.

      NOTE

      If MFA is enabled for the user, Veeam Backup for Microsoft Azure returns an MFA token in the response body. To learn how to obtain an access token and a refresh token when MFA is enabled, see Requesting Authorization.

      Recieving Authorization Tokens

    6. Save the access and refresh token locally for further use.

      TIP

      You can download a server response in the JSON format. To do that, in the expanded method window, click Download at the lower right corner of the Response body field.

  2. Authorize your access in the Swagger UI:

    1. At the top right corner of the Veeam Backup for Microsoft Azure API page, click Authorize.

      Getting Authorization

      The Available authorizations window will open.

    2. In the Available authorizations window, insert the access token saved locally in the Value field. Use the Bearer <access_token> format.

      Available Authorizations Window

    3. Click Authorize.

  3. When the access token expires, use the refresh token:

    1. On the Veeam Backup for Microsoft Azure API page, expand the Login resource and click POST api/oauth2/token.

    2. In the expanded method window, click Try it out.

    3. From the grant_type drop-down list, select Refresh_token.

    4. In the refresh_token field, insert the refresh token saved locally, and click Execute.

      Requesting Authorization Tokens

      Wait for the response from the server. A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.

      Receiving Authorization Tokens

    5. Save the access and refresh token locally for further use. To authorize your access in the Swagger UI, repeat step 2.

  4. When you finish working with the Swagger UI:

    1. At the top right corner of the Veeam Backup for Microsoft Azure API page, click Authorize.

      The Available authorizations window will open.

    2. In the Available authorizations window, click Logout.

      Logging Out

Sending Requests

After you get authorization, you can send HTTP requests to REST API collections and resources in the Swagger UI.

To send a request:

  1. On the Veeam Backup for Microsoft Azure API page, expand a resource to which you want to perform an operation.

  2. In the list of request methods, click the required method.

  3. In the expanded method window, click Try it out.

  4. Enter parameter values if required.

  5. Click Execute.

    Sending Request

    The Swagger UI returns a response body as well as a response code and response headers. Additionally the Swagger UI generates a curl command and a URL for your request.

    TIP

    You can download a server response in the JSON format. To do that, in the expanded method window, click Download at the lower right corner of the Response body field.

    Getting Response