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.

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

Veeam Backup for AWS REST API requests use the following base URL format:

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

where:

• <hostname> is a public IPv4 address or DNS hostname of the EC2 instance where Veeam Backup for AWS is installed.

• <port> is the number of a port used to communicate with the REST API service running on the backup appliance.

  The default port number is 11005. You can change the default REST API port as described in section Configuring Security Settings.

  IMPORTANT
  

  The port required to communicate with the REST API service must be opened on the backup appliance. To open the port, you must add an inbound rule to the security group associated with the backup appliance. To learn how to add rules to security groups, see AWS Documentation.

• <version> is an API version.

  The current version is v1.

To get a collection of Veeam Backup for AWS REST API resources, request the base URL followed by a resource collection endpoint. For example:

https://127.0.0.1:11005/api/v1/virtualMachines

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

https://127.0.0.1:11005/api/v1/virtualMachines/c36824e9-0c3e-4892-8dff-44fd56968506

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

[
   {
      "id": "c36824e9-0c3e-4892-8dff-44fd56968506",
      "name": "forBackup",
      ...
   },
   {
      "id": "8cbd230f-0694-4b4d-b831-6308cafd6022",
      "name": "vb-test-byol",
      ...
   }
]

The Veeam Backup for AWS REST API is available in multiple versions. To work with resources available in a particular version of the REST API specification, you must specify the version in the x-api-version header. For example, to obtain information on EFS backup policies using the latest Veeam Backup for AWS REST API specification, send the following HTTP request to the backup appliance:

Request:
GET https://127.0.0.1:11005/api/v1/efs/policies

Request Header:
`x-api-version`:1.7-rev0

The Veeam Backup for AWS 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 AWS resources if the specification version has been released earlier or with the product version installed on the backup appliance:

Veeam Backup for AWS 9

• v1 (1.7-rev0)
• v1 (1.6-rev0)
• v1 (1.5-rev1)
• v1 (1.5-rev0)

Veeam Backup for AWS 8.0

• v1 (1.6-rev0)
• v1 (1.5-rev1)
• v1 (1.5-rev0)
• v1 (1.4-rev0)

Veeam Backup for AWS 7.0

• v1 (1.5-rev1)
• v1 (1.5-rev0)
• v1 (1.4-rev0)
• v1 (1.3-rev0)

Veeam Backup for AWS 6a

• v1 (1.4-rev0)
• v1 (1.3-rev0)

Veeam Backup for AWS 6.0

• v1 (1.4-rev0)
• v1 (1.3-rev0)

Veeam Backup for AWS 5.0, 5a

• v1 (1.3-rev0)
• v1 (1.2-rev0)
• v1 (1.1-rev0)
• v1 (1.0-rev0)

Veeam Backup for AWS 4.0

• v1 (1.2-rev0)
• v1 (1.1-rev0)
• v1 (1.0-rev0)

Veeam Backup for AWS 3.0

• v1 (1.1-rev0)
• v1 (1.0-rev0)

Veeam Backup for AWS 2.0

v1 (1.0-rev0)

To start working with the Veeam Backup for AWS REST API, users must first authenticate themselves and get authorization to make requests. Veeam Backup for AWS controls access to its functionality with the help of user roles. A role defines what operations users can perform and what range of data is available to them in the Veeam Backup for AWS REST API. For more information on user roles, see the Veeam Backup for AWS User Guide, section Managing Permissions.

Veeam Backup for AWS 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.
• 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, the Veeam Backup for AWS REST API access token expires in 1 hour, refresh token expires in 2 hours. You can change the token lifetime policy to meet the necessary security requirements. For more information, see Configuring Security Settings.

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

Veeam Backup for AWS 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.

The Veeam Backup for AWS REST API accepts the following grant types to authenticate a Veeam Backup for AWS user:

• Password
• MFA
• Authorization Code

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

To obtain authorization tokens, a user sends the HTTP POST request to the api/v1/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 AWS. For more information on how to create users, see User Accounts or the Veeam Backup for AWS User Guide, section Adding User Accounts.

A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS 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 AWS 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.

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 api/v1/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 AWS returns an mfa token.

2. To obtain an access token and a refresh token, the user must send another HTTP POST request to the api/v1/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 the authentication application running on the trusted device.

   A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS 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 AWS 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.

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

1. To obtain the authorization code, an authorized user sends the HTTP POST request to the api/v1/token/authorization_code endpoint.

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

   NOTE
   

   By default, the Veeam Backup for AWS authorization code expires in 60 seconds. To change the authorization code lifetime, see Configuring Security Settings.

2. To obtain an access token and a refresh token, a user or client application sends the HTTP POST request to the api/v1/token endpoint. The request body must contain the grant_type parameter with the specified authorization_code value and the authorization code previously issued by the authorization server.

   A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS 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 AWS REST API. The refresh token must be saved locally.

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

To get authorization using single sign-on, a user must first obtain a SSO URL that will be used to log in to the identity provider portal, and then get authorization tokens.

1. To obtain the SSO URL, a user sends the HTTP GET request to the api/v1/identityProvider/signOnUrl endpoint. The userName query parameter must be sent as part of the URL. Use the question mark ? to separate the parameter from the endpoint.

   A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS returns the SSO URL, which must be used to authenticate the user on the identity provider portal and obtain a SAML response from the identity provider.

2. To obtain a SAML response, the user sends HTTP POST requests to the SSO URL obtained from the Veeam Backup for AWS authorization server. The request body must contain the credentials of the user in the format accepted by the identity provider.

   A successfully completed operation returns the SAML response that must be passed to the Veeam Backup for AWS REST API.

3. To obtain an access token and a refresh token, a user sends the HTTP POST request to the api/v1/identityProvider/token endpoint. The request body must contain the SamlResponse parameter with the specified SAML response value previously issued by the identity provider server.

   A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS 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 AWS REST API. The refresh token must be saved locally.

To learn how to authorize your access using single sign-on, see Example [Single Sign-On]. 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/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for AWS REST API.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://127.0.0.1:11005/api/v1/token

Request Header:
`x-api-version`:1.7-rev0

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.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTUzNzksImV4...",
   "token_type": "bearer",
   "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6ImQ5ZDhiN2Rl...",
   "expires_in": 3600,
   ".issued": "2020-06-12T10:29:39",
   ".expires": "2020-06-12T10:44:39",
   "username": "administrator"
}

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 api/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for AWS REST API.

   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://127.0.0.1:11005/api/v1/token
   
   Request Header:
   `x-api-version`:1.7-rev0
   
   Request Body:
   grant_type=password&username=administrator&password=Password1
   

   The server sends a response in the following format.

   Response:
   200
   
   Response Body:
   {
      "username": "administrator",
      "mfa_enabled": true,
      "mfa_token": "NkZFMzc4RjA4NzJCQzk1QjU3NTY1Mzc2RTU1MjVCODkzOThDQjdGODMzNDVDMEY0QUZGRTIzMjZFQTNDQ0QxRg=="
   }
   

2. To obtain an access token and a refresh token, the user sends the HTTP POST request to the api/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for AWS REST API.

   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 by the authentication application running on the trusted device.

   Request:
   POST https://127.0.0.1:11005/api/v1/token
   
   Request Header:
   x-api-version:1.7-rev0
   
   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": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTUzNzksImV4...",
      "token_type": "bearer",
      "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6ImQ5ZDhiN2Rl...",
      "expires_in": 3600,
      ".issued": "2020-06-12T10:29:39",
      ".expires": "2020-06-12T10:44:39"
   }
   

Example [Authorization Code]

To access the REST API using an authorization code, a user must do the following:

1. To obtain an authorization code, an authorized user sends the HTTP POST request to the api/v1/token/authorization_code endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for AWS REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

   Request:
   POST https://127.0.0.1:11005/api/v1/token/authorization_code
   
   Request Header:
   x-api-version:1.7-rev0
   Authorization:Bearer eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQi-LCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTUzNzksImV4...
   

   The server sends a response in the following format.

   Response:
   200
   
   Response Body:
   {
      "code": "AAEAAJO1R+DANfH7JDlyUzDVYGDw+77dyaa0mFu8nozvbOreW31Uu1X+mejLUilSp6nBrhcmv9/LTjAjMz3P+grbg1OATjZN7kZ5XbhenJG7DrVUtvpA6h5aDmma8INsMv6xW7+TmcOUNlK65n2J2/rQCjg80rMOS..."
   }
   

2. To obtain an access token and a refresh token, the user sends the HTTP POST request to the api/v1/token endpoint. In the x-api-version header, the current revision of the Veeam Backup for AWS REST API must be specified.

   In the request body, the user specifies 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://127.0.0.1:11005/api/v1/token
   
   Request Header:
   x-api-version:1.7-rev0
   
   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.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNjQxNjAsImV4...",
      "token_type": "bearer",
      "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6IjQwZTA4ZmJmL...",
      "expires_in": 3600,
      ".issued": "2020-04-12T12:56:00",
      ".expires": "2020-04-12T13:11:00"
   }
   

Example [Single Sign-On]

To access the REST API using SSO, a user must do the following:

1. To obtain SSO URL, a user sends the HTTP GET request to the api/v1/identityProvider/signOnUrl endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for AWS REST API. The name of the user must be specified as a value of the userName query parameter.

   Request:
   GET https://127.0.0.1:11005/api/v1/identityProvider/signOnUrl?userName=sara_baker@companymail.com
   
   Request Header:
   x-api-version:1.7-rev0
   

   The server sends a response in the following format.

   Response:
   200
   
   Response Body:
   {
      "redirectToUrl": "https://company.companymail.com/adfs/ls/?SAMLRequest=lJExb4MwEIX%2FCvJ%2BGJMAsQWoiVClSG2HJsrQBRnjKLRgpz6jVvn1JTRDhw7tdnr3nt6nu3w9%2BpN51u%2BjRh9sq4LUacNb1iyX0KqMw1K2KXCuOKyOR56lSaR5lpHgoB121hQkDiMSbBFHvTXopfGTFMURMAZxumepiFYiYS8kqKaGzkg%2Fp07en1FQqlUMC2ARAw5ssQrtBfzkg9YOsjNhb5XsqWyPSHukJLi3TukZuSDejZoEn0NvsCCjM8JK7FAYOWgUXond%2BvFBTHTi7Ky3yvakzGdO95eQRNTuykrK%2FaaqD5t6Rk2AZQxYMtHGi1DZ4Tx6DSyUg7xYIz%2FwquX0u6fMd2PzqpX%2FZ2H%2BNG23VYnSybqRb9rd%2FXaXnN58Ob31TNPPf5ZfAAAA%2F%2F8DAA%3D%3D"
   }
   

2. To obtain a SAML response from the identity provider, the user sends the HTTP POST request to the SSO URL.

   In the request body, the user specifies user credentials in the format accepted by the identity provider. The Content-Type header value must be specified. By default, the content type value of the authorization request is x-www-form-urlencoded.

   Request:
   POST https://company.companymail.com/adfs/ls/?SAMLRequest=lJExb4MwEIX%2FCvJ%2BGJMAsQWoiVClSG2HJsrQBRnjKLRgpz6jVvn1JTRDhw7tdnr3nt6nu3w9%2BpN51u%2BjRh9sq4LUacNb1iyX0KqMw1K2KXCuOKyOR56lSaR5lpHgoB121hQkDiMSbBFHvTXopfGTFMURMAZxumepiFYiYS8kqKaGzkg%2Fp07en1FQqlUMC2ARAw5ssQrtBfzkg9YOsjNhb5XsqWyPSHukJLi3TukZuSDejZoEn0NvsCCjM8JK7FAYOWgUXond%2BvFBTHTi7Ky3yvakzGdO95eQRNTuykrK%2FaaqD5t6Rk2AZQxYMtHGi1DZ4Tx6DSyUg7xYIz%2FwquX0u6fMd2PzqpX%2FZ2H%2BNG23VYnSybqRb9rd%2FXaXnN58Ob31TNPPf5ZfAAAA%2F%2F8DAA%3D%3D
   
   Request Header:
   x-api-version:1.7-rev0
   Content-Type:x-www-form-urlencoded
   
   Request Body:
   {
      "UserName": "sara_baker@oz-test-domain.local",
      "Password": "Admin345Dept01"
   }
   

   The server sends a response in the following format.

   Response:
   200
   
   Response Body:
   {
      "name": "SAMLResponse",
      "value": "PHNhbWxwOlJlc3BvbnNlIElEPSJfNDMyNDQ5YTItYjNiMi00M2U4LTk5MmItMTI1MGY0MWJjYjQ5IiBWZXJzaW9uPSIyLjAiIElzc3VlSW5zdGFudD0iMjAyMC0xMS0yNVQxMTozMjo1OS40NzBaIiBEZXN0aW5hdGlvbj0iaHR0cHM6Ly9lYzItMzUtMTcxLTE1OS0xMjMuY29tcHV0ZS0xLmF..."
   }
   

3. To obtain an access token and a refresh token, the user sends the HTTP POST request to the api/v1/identityProvider/token endpoint. In the x-api-version header, the current revision of the Veeam Backup for AWS REST API must be specified.

   In the request body, the user specifies the SamlResponse parameter — the SAML response value obtained from the identity provider server.

   Request:
   POST https://127.0.0.1:11005/api/v1/identityProvider/token
   
   Request Header:
   x-api-version:1.7-rev0
   
   Request Body:
   SamlResponse=PHNhbWxwOlJlc3BvbnNlIElEPSJfNDMyNDQ5YTItYjNiMi00M2U4LTk5MmItMTI1MGY0MWJjYjQ5IiBWZXJzaW9uPSIyLjAiIElzc3VlSW5zdGFudD0iMjAyMC0xMS0yNVQxMTozMjo1OS40NzBaIiBEZXN0aW5hdGlvbj0iaHR0cHM6Ly9lYzItMzUtMTcxLTE1OS0xMjMuY29...
   

   The server sends a response in the following format.

   Response:
   200
   
   Response Body:
   {
      "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNjQxNjAsImV4...",
      "token_type": "bearer",
      "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6IjQwZTA4ZmJmL...",
      "expires_in": 3600,
      ".issued": "2020-04-12T12:56:00",
      ".expires": "2020-04-12T13:11:00"
   }
   

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 api/v1/token endpoint. A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.

Example

To obtain an access token and a refresh token, a user sends the HTTP POST request to the api/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for AWS REST API.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://127.0.0.1:11005/api/v1/token

Request Header:
x-api-version:1.7-rev0

Request Body:
grant_type=refresh_token&refresh_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6ImQ5ZDhiN2RlLWIwYjU...

The server sends a response in the following format.

Response:
200

Response Body:
{
   "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTU3ODMsImV4cCI6MT...",
   "token_type": "bearer",
   "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6ImI5MjJhNGJiLTJmY2...",
   "expires_in": 3600,
   ".issued": "2020-04-07T10:36:23",
   ".expires": "2020-04-07T10:51:23"
}

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

Example

To log out, a user sends the HTTP DELETE request to the api/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for AWS REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

Request:
DELETE https://127.0.0.1:11005/api/v1/token

Request Header:
x-api-version:1.7-rev0
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrLa1Lm41LsjpMiiPZytkqIUUiphhlXn7Vm10xlTzQUe0TU3HmXK-KD2MiB6qBImaISkEjgCmyIsurSN2mHi1Qo8V...

The server sends a response in the following format.

Response:
204

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

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 /api/v1/users/{userId}/enableMfa endpoint, where {userId} is a name of the user for which you want to enable MFA.

   In the x-api-version header, specify the current revision of the Veeam Backup for AWS REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

   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://127.0.0.1:11005/api/v1/users/administrator/enableMfa
   
   Request Header:
   x-api-version:1.7-rev0
   Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtA...
   
   Request Body:
   {
      "recreate": "false"
   }
   

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

   Response:
   200
   
   Response Body:
   {
      "userName": "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 AWS. 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 /api/v1/users/{userId}/acceptMfa endpoint.

   In the x-api-version header, specify the current revision of the Veeam Backup for AWS REST API, 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://127.0.0.1:11005/api/v1/users/administrator/acceptMfa
   
   Request Header:
   x-api-version:1.7-rev0
   Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtA...
   
   Request Body:
   {
      "code": "475112",
      "token": "M0Q1OEMwOEQ5MTRFNzMwMzE5MTkzMUU5MDVCNjNENzREMTQ0MDYyRUJFNEE0QjI5MzEzNzVEMUE1QURFNzBENA=="
   }
   

   A successfully completed operation returns the 201 response code.

   Response:
   201
   

   NOTE
   

   In case of losing access to the authentication application:

   • To get authorization in Veeam Backup for AWS, the user can use a recovery scratch code saved locally instead of a verification code. Each recovery code can be used only once.
   • To recreate 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.

To disable MFA for a specific user, send the HTTP POST request to the /api/v1/users/{userId}/disableMfa endpoint, where {userId} is a name of the user for which you want to disable MFA.

In the x-api-version header, specify the current revision of the Veeam Backup for AWS REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

Request:
POST https://127.0.0.1:11005/api/v1/users/administrator/disableMfa

Request Header:
x-api-version:1.7-rev0
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtA...

A successfully completed operation returns the 204 response code.

Response:
204

The Veeam Backup for AWS 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 AWS 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
   

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

   3. Save the changes.

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

   2. Set the new port number.

   listen <port_number> ssl;
   

   3. Save the changes.

   4. Restart the nginx service to apply the changes.

   sudo service nginx restart
   

To perform operations with Veeam Backup for AWS 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.

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

• Offset Parameter
• Limit Parameter
• SearchPattern Parameter
• Sort Parameters
• Filter Parameters

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

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 AWS regions starting from the third one in the /regions collection, send the following request:

GET https://127.0.0.1:11005/api/v1/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 AWS REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use the Sort, SearchPattern or one of the filter query parameters. Note that the Sort, 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.

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 EC2 instances in the /virtualMachines collection, send the following request:

GET https://127.0.0.1:11005/api/v1/virtualMachines?Limit=3

The Veeam Backup for AWS REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use the Sort, 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.

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 EC2 instances whose name contains the ubuntu search pattern in the /virtualMachines collection, send the following request:

GET https://127.0.0.1:11005/api/v1/virtualMachines?SearchPattern=ubuntu

The Sort query parameter is used to sort items of a resource collection in a response. Some resource properties of Veeam Backup for AWS REST API schemas can be used as parameter values for the Sort query parameter.

The Veeam Backup for AWS REST API accepts the following direction specifiers:

Direction Specifier	Description
ASC	Defines the ascending order of the resource collection representation.
DESC	Defines the descending order of the resource collection representation.

For example, to sort items of the /repositories resource collection by the Amazon S3 bucket where the S3 repository is located in the ascending order, send the following request:

GET https://127.0.0.1:11005/api/v1/repositories?Sort=amazonBucketAsc

Some resource properties of Veeam Backup for AWS 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 EC2 instances of the /virtualMachines collection, send the Protected value of the ProtectionStatus filter parameter in the following request:

GET https://127.0.0.1:11005/api/v1/virtualMachines?ProtectionStatus=Protected

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

The Veeam Backup for AWS 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 AWS REST API, in a web browser, navigate to the following URL:

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

where:

• <hostname> is a public IPv4 address or DNS hostname of the EC2 instance on which Veeam Backup for AWS is installed.
• <port> is the REST API port number set during Veeam Backup for AWS installation.

The default port number is 11005.

In the Select a definition field, select the version and revision of the Veeam Backup for AWS REST API.

Veeam Backup for AWS 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 AWS public API page, expand the Token resource and click POST api/v1/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 AWS.

      NOTE
      

      To learn how to obtain an access token for a user whose identity has been retrieved from the identity provider, see Authorization (Single Sign-On).

   5. Click Execute.

      

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

      NOTE
      

      If MFA is enabled for the user, Veeam Backup for AWS 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.

      

   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 AWS public API page, click Authorize.

      

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

      

   3. Click Authorize.

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

   1. On the Veeam Backup for AWS public API page, expand the Token resource and click POST api/v1/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.

      

      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.

      

   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 AWS public API page, click Authorize.

   2. In the Available authorizations window, click Logout.

      

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

To send a request:

1. On the Veeam Backup for AWS public 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.

   

   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.