Veeam Recovery Orchestrator 7.2
REST API Reference
Related documents

Overview

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

Resource URLs

Each Orchestrator REST API-exposed entity has a resource representing it. To get a resource representation, request its URL.

Orchestrator REST API v7.21 requests use the following new base URL format:

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

where:

  • <FQDN> is a DNS name or IP address of the machine where the Orchestrator server runs.

  • <port> is the Web UI port number specified during Orchestrator installation.

    The default port number is 9898.

  • <version> is an API version.

    The current version is v7.21.

NOTE

Only the v7.1, 7.2 and v7.21 versions of the Orchestrator REST API are supported.

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

https://uwin2012r2lt.n.local:9898/api/v7.21/Plans

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

https://uwin2012r2.n.local:9898/api/v7.21/Plans/b063f440-2f15-45aa-a8f7-196be6f652ba

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

[
  {
    "name": "Columbus",
    "id": "12f39f64-245e-4430-a82e-126497007641",
    ...
  },

  {
    "name": "Ontario",
    "id": "b063f440-2f15-45aa-a8f7-196be6f652ba",
    ...
  }
]

Versioning

The Veeam Recovery Orchestrator REST API is available in multiple versions. The Veeam Recovery Orchestrator 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 Recovery Orchestrator resources if the specification version has been released earlier or with the product version installed on the backup appliance:

Veeam Recovery Orchestrator 7

Veeam Disaster Recovery Orchestrator 6

Veeam Disaster Recovery Orchestrator 5

Veeam Availability Orchestrator 4

Authorization and Security

To start working with the Orchestrator REST API, users must first authenticate themselves. Orchestrator 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 that must be used in all requests during the current logon session.
  • Refresh token is a string that represents authorization granted to the client that can be used to obtain a new access token if the current access token expires or becomes lost.
  • MFA token is a string that represents pre-authorization granted to the client that can be used to obtain access and refresh tokens.

Veeam Recovery Orchestrator REST API authorization process involves the following procedures:

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

Requesting Authorization

To obtain an access token and a refresh token, a user sends the HTTP POST request to the Orchestrator /api/token path:

https://<FQDN>:<port>/api/token

The request body must contain the credentials of an account with the Orchestrator Administrator, Plan Author or Plan Operator privileges. The user name must be specified in the DOMAIN\USERNAME or USERNAME format.

For more information on how to assign Orchestrator user roles, see the Veeam Recovery Orchestrator User Guide, section Managing User Accounts.

NOTE

Simultaneous sessions initiated in different client applications under the same credentials may interfere with each other. To avoid unexpected logout, a user can create a dedicated client account for each application. For more information on how to work with client accounts, see Working with Clients.

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

TIP

By default, the Orchestrator REST API access token expires in 15 minutes. You can change the token lifetime policy to meet the necessary security requirements. For more information, see Configuring Token Lifetime.

To learn how to authorize your access, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

Using Refresh Token

To obtain a new pair of tokens in case the access token expires or becomes lost, the user sends the HTTP POST request with the refresh token in the request body to the Orchestrator /api/token path. 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.

To learn how to use refresh tokens, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

Performing Logout

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

To learn how to log out, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

Working with Clients

The Veeam Recovery Orchestrator REST API uses the OAuth 2.0 authorization protocol. The protocol allows various client applications to authenticate themselves in the Orchestrator REST API using client credentials. This type of credentials helps applications work with the REST API simultaneously and avoid interference from each other.

To establish an identity for every application, a user creates client accounts. Clients inherit the user permissions in the Orchestrator REST API.

To work with client accounts, the Orchestrator REST API uses the following procedures:

Creating Clients

To create a client account, a user sends the HTTP POST request to the api/v7.21/Clients endpoint. In the Authorization header, the user specifies the currently valid access token.

A successfully completed operation returns the 200 response code. In the response body, Orchestrator returns a client ID and client secret. The client credentials must be saved locally.

IMPORTANT

If you lose a client secret, you will have to create a new client account. The client whose client secret was lost become useless and can be deleted by the user.

NOTE

Clients cannot create new client accounts.

To learn how to create clients, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

Requesting Client Authorization

To obtain a pair of tokens, a client sends the HTTP POST request to the Orchestrator /api/token path. The request body must contain the client ID and client secret.

A successfully completed operation returns the 200 response code. In the response body, Orchestrator returns an access token, its expiration time and a refresh token. The client inserts the access token in headers of further requests to the Orchestrator REST API. The refresh token must be saved locally.

To learn how to obtain an access and refresh token under a client account, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

Getting Clients

To get all client IDs related to a user account, the user sends the HTTP GET request to the api/v7.21/Clients endpoint. In the Authorization header, the user specifies the currently valid access token.

A successfully completed operation returns the 200 response code. In the response body, Orchestrator returns a list of client IDs created by the user.

NOTE

A client can get only its own client ID.

To learn how to get client accounts, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

Deleting Clients

If a client is no longer needed (for example, when the client finishes working with Orchestrator REST API), the client account can be deleted by sending the HTTP DELETE request with the specified client ID to the api/v7.21/Clients endpoint. The clientId parameter must be specified in the request URL. A successfully completed operation returns the 204 response code.

NOTE

A user can delete all related client accounts. A client can delete only his own client account.

To learn how to delete clients, see Example Requests and Responses. Alternatively, you can use the Swagger UI.

Configuring Token Lifetime

The default token lifetime policy that applies to Orchestrator REST API tokens is 15 minutes for an access token and 120 min for a refresh token. However, a user can change the token lifetime defaults to meet the necessary security requirements.

To specify the lifetime of tokens issued by the Orchestrator REST API, do the following:

  1. On the machine running the Orchestrator server, locate the Web.config configuration file.

    By default, the file is located in the C:\Program Files\Veeam\Web UI folder.

  2. Open the Web.config file in Notepad or any other editor.

  3. Locate the AuthenticationSettings tag, and set the new values for the accessTokenExpireMinutes and refreshTokenExpireMinutes parameters.

    <AuthenticationSettings accessTokenExpireMinutes="15" refreshTokenExpireMinutes="120"/>

  4. Save the changes.

  5. Restart the Veeam Recovery Orchestrator site to apply the changes:

    1. Open the Internet Information Services (IIS) Manger.

    2. In the Connections pane, expand the server node and navigate to Sites > Veeam Recovery Orchestrator Web UI.

    3. In the Manage Website pane, click Restart.

Example Requests and Responses

The following example illustrates how a user and the server communicate using requests and responses.

  1. To obtain an access token and a refresh token, a user sends the HTTP POST request to the Orchestrator /api/token path.

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

    • grant_type — the authorization process requires that the password value must be specified for this parameter.

    • username and password — credentials used to access the server; in this example, vro\administrator and Password1 are used.

    Request:
POST https://uwin2012r2.n.local:9898/api/token

Request Header:
content-type:application/x-www-form-urlencoded

Request Body:
grant_type=password&username=vro\administrator&password=Password1

    The server sends a response in the following format.

    Response:
200

Response Body:
{
  "access_token": "0G072fREAFX3G2hIOQYiCLxvx-NvSra2GtQMxUHHPFsh9a3RNmI2R6VI6evgdvIopQSLo6nAy_SvZ6YnQagc5vlJOcSzfMjU3LiRxUuE7VdTydd4Br6mpMCmxaGTIrFhnrhiBKqqVbhcXiVppx-lLOjFzO379fsyyXspmnnuhjzHdlTKTa4V5VDKrtpfoOZyiz1Pa8_r9JtPc0D6vldUbQ-bEskoXkZGbyEOb4kYk8XqLm69GGTmn4bO8_da2fPwH4yjj2yP5vxmTZi3Rto47YyPbW98l2-s4ocd3nJXsHYD-csU1U4zCTzfLENKR_JB",
  "token_type": "bearer",
  "expires_in": 899,
  "refresh_token": "Yp5SaGYSR6ChFkr9T5LJ2PcNNGAR+Df9ixOALtAsOD0="
}

  2. [Applies only if a dedicated client account is required]

    To create a client account, the user sends the HTTP POST request to the api/v7.21/Clients endpoint.

    In the Authorization header, the user specifies the currently valid access token in the Bearer <access_token> format.

    Request:
POST https://uwin2012r2.n.local:9898/api/v7.21/Clients

Request Header:
Authorization: Bearer 0G072fREAFX3G2hIOQYiCLxvx-NvSra2GtQMxUHHPFsh9a3RNmI2R6VI6evgdvIopQSLo6nAy_SvZ6YnQagc5vlJOcSzfMjU3LiRxUuE7VdTydd4Br6mpMCmxaGTIrFhnrhiBKqqVbhcXiVppx-lLOjFzO379fsyyXspmnnuhjzHdlTKTa4V5VDKrtpfoOZyiz1Pa8_r9JtPc0D6vldUbQ-bEskoXkZGbyEOb4kYk8XqLm69GGTmn4bO8_da2fPwH4yjj2yP5vxmTZi3Rto47YyPbW98l2-s4ocd3nJXsHYD-csU1U4zCTzfLENKR_JB

    The server sends a response in the following format.

    Response:
200

Response Body:
{
  "client_id": "4a346f40-d4b6-4ed8-913d-d6e1297a75a4",
  "client_secret": "AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAA88p/hgiPqUG5Ianexa8klAQAAAACAAAAAAAQZgAAAAEAACAAAAAKaqFPz0480AeOmARrLL9l76H8x22PD98B7BSTzkIO8gAAAAAOgAAAAAIAACAAAABPK3q/7A6EWS2KVvXTWiz4O7xrdoPNBk2qiY43MOuGVjAAAACPhL6JAEQCTYTItygVLo8i16ZdzdPXZ3l1KM6XBrDKbEyAKLFHmeb4jV5Deo0jKWNAAAAAdi7slKgOZR6JTqseaK3uHAXOxknjagjBStrZ61EPeYp23R28tlzq6FiZ/JW76XJ4yqHj96t2Q8XSijhzKFV5KA=="
}

  3. [Applies only if a dedicated client account is required]

    To obtain an access under the client account, the client sends the HTTP POST request to the Orchestrator /api/token path.

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

    • grant_type — the authorization process requires that the client_credentials value must be specified for this parameter.

    • client_id and client_secret — credentials used to access the server.

    Request:
POST https://uwin2012r2.n.local:9898/api/token

Request Header:
content-type: application/x-www-form-urlencoded

Request Body:
grant_type=client_credentials&client_id=58b91a67-4aca-490f-aeac-2ea11eadceaa&client_secret=iGuL5owQoVbN/RfaWYPTjh4QHT+1ylQlqiwKR+PS/jA=

    The server sends a response in the following format.

    Response:
200

Response Body:
{
  "access_token": "RknUZHexLF2i_TyAqusCrT0UwTosECThrK-ZDKCrkLlKClG19Wmrr0CCMvas0wvddmbeVy345I404g52Ck26gDGKI1YuAjI6vYQZf78D_cE6MIrdqF6ckQRZkGtpInk8NO_pwAllhcowDfIgEOHZ39mTvUVVgkMovKrA_4az2E50G1-IRctPcdK3ivrJHrsUaG5oIg69YRrh_uPrFMXYk2xIEfoO8ehNsB_Vm1S_ngjMS2I6DICG4cPQboc7efO3L-BBxwnyj4lNYOSvIztkQxDuYAw5f06efHfwbP_ZksGmRZWUZcHvDVVUJZ3YJiQg7977LeyK9cQ847-nKIwlBw2jRR0MTstsgLIe44RLlyY",
  "token_type": "bearer",
  "expires_in": 899,
  "refresh_token": "aUCl0dAA9FNg1FR3f1ShgzoznDTZIxGKjrtSzIabtoo=",
}

  4. To refresh the pair of tokens, the user or client sends the HTTP POST request to the Orchestrator /api/token path.

    In the body of the request, the user or client 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://uwin2012r2.n.local:9898/api/token

Request Header:
Content-Type: application/x-www-form-urlencoded

Request Body:
grant_type=refresh_token&refresh_token=aUCl0dAA9FNg1FR3f1ShgzoznDTZIxGKjrtSzIabtoo%3D

    The server sends a response in the following format.

    Response:
200

Response Body:
{
  "access_token": "YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrLa1Lm41LsjpMiiPZytkqIUUiphhlXn7Vm10xlTzQUe0TU3HmXK-KD2MiB6qBImaISkEjgCmyIsurSN2mHi1Qo8VlZadnhkBd3v6nD5GEb8Gh4Zw7YAv5klmrnM0iBu7xhev2hVMZvKHGXvGshI3gS24-hIWbSsBGarVnRLSiUzor6QExTGShSa7pIeJWsAtJXLF5a3oSUooUv_YMYe8d5iZEouUuirrw",
  "token_type": "bearer",
  "expires_in": 899,
  "refresh_token": "vbGuPkz7XLS1p5PQ3EARoGGKJKFMdgBbIi6fH79WQac="
}

  5. To get all client IDs related to the user account, the user sends the HTTP GET request to the api/v7.21/Clients endpoint. The client can get only its own ID using this request.

    In the Authorization header, the user or client specifies the currently valid access token in the Bearer <access_token> format.

    Request:
GET https://uwin2012r2.n.local:9898/api/v7.21/Clients

Request Header:
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrLa1Lm41LsjpMiiPZytkqIUUiphhlXn7Vm10xlTzQUe0TU3HmXK-KD2MiB6qBImaISkEjgCmyIsurSN2mHi1Qo8VlZadnhkBd3v6nD5GEb8Gh4Zw7YAv5klmrnM0iBu7xhev2hVMZvKHGXvGshI3gS24-hIWbSsBGarVnRLSiUzor6QExTGShSa7pIeJWsAtJXLF5a3oSUooUv_YMYe8d5iZEouUuirrw

    The server sends a response in the following format.

    Response:
200

Response Body:
[
  "4a346f40-d4b6-4ed8-913d-d6e1297a75a4",
  "b2845041-53ce-4335-b157-bcf9b08740c8",
  "98e3c3cc-5945-4b30-9e89-6066e5159502",
  "3ace3638-3810-4f0f-92e6-d700ad5df6ba",
  "06af349a-acba-4f42-9f81-721489bcae4c"
]

  6. To delete a client account, the user sends the HTTP DELETE request to the api/v7.21/Clients endpoint. The client can delete only his own client account using this request.

    In the Authorization header, the user or client specifies the currently valid access token in the Bearer <access_token> format.

    In the clientId parameter, the user specifies an ID of the client to be deleted, the client specifies its own client ID.

    Request:
DELETE https://uwin2012r2.n.local:9898/api/v7.21/Clients?clientId=4a346f40-d4b6-4ed8-913d-d6e1297a75a4

Request Header:
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrLa1Lm41LsjpMiiPZytkqIUUiphhlXn7Vm10xlTzQUe0TU3HmXK-KD2MiB6qBImaISkEjgCmyIsurSN2mHi1Qo8VlZadnhkBd3v6nD5GEb8Gh4Zw7YAv5klmrnM0iBu7xhev2hVMZvKHGXvGshI3gS24-hIWbSsBGarVnRLSiUzor6QExTGShSa7pIeJWsAtJXLF5a3oSUooUv_YMYe8d5iZEouUuirrw

    The server sends a response in the following format.

    Response:
204

  7. To log out, the user or client sends the HTTP DELETE request to the api/token endpoint.

    In the Authorization header, the user or client specifies currently valid access token in the Bearer <access_token> format.

    Request:
DELETE https://uwin2012r2.n.local:9898/api/token

Request Header:
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrLa1Lm41LsjpMiiPZytkqIUUiphhlXn7Vm10xlTzQUe0TU3HmXK-KD2MiB6qBImaISkEjgCmyIsurSN2mHi1Qo8VlZadnhkBd3v6nD5GEb8Gh4Zw7YAv5klmrnM0iBu7xhev2hVMZvKHGXvGshI3gS24-hIWbSsBGarVnRLSiUzor6QExTGShSa7pIeJWsAtJXLF5a3oSUooUv_YMYe8d5iZEouUuirrw

    The server sends a response in the following format.

    Response:
204

HTTP Methods

To perform operations with Orchestrator 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 Orchestrator REST API returns for a resource or collection, you can use the following Orchestrator REST API query parameters:

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

Any resource property of a Orchestrator REST API resource schema can be used as a parameter value for the filter and sort Orchestrator REST API query parameters. For example, to return a list of restore plans, use the planType property of the /Plans resource model as a parameter value for the filter query parameter in the following request:

GET https://uwin2012r2.n.local:9898/api/v7.21/Plans?filter=[{"property":"planType","operator":"==","value":"Restore"}]

Filter Parameter

The filter query parameter is used to filter items in 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.

The filter parameter accepts the array data type. To filter a resource collection use the filter query parameter in the following format:

GET https://<FQDN>:<port>/api/<version>/<endpoint>?filter=[{"property":"<property>","operator":"<operator>","value":"<value>"}]

where:

  • <endpoint> is the resource collection endpoint.
  • <property> is the resource property name.
NOTE

To filter a resource collection based on a property of a resource subschema, use the <subschema>.<property> format to specify the resource property name where <subschema> is the subschema name.

  • <operator> is a relational or logical operator used in the Orchestrator REST API.
  • <value> is a resource property value.

The Orchestrator REST API supports the following operators:

Operator Description
== (equal) Returns resources that match the specified property value.
!= (not equal) Returns resources that do not match the specified property value.
> (greater than) Returns resources with the property value that is greater than the specified value.
< (less than) Returns resources with the property value that is less than the specified value.
in Returns resources that match at least one of the values specified for a property.
&& (logical AND) Returns resources that match all the specified property values.
**
like [Applies only to properties with the string data type] Returns resources that match a specified pattern in the property value.

Examples

  • To get a representation of a plan with the specified name, send the following request:

    GET https://uwin2012r2.n.local:9898/api/v7.21/Plans?filter=[{"property":"name","operator":"==","value":"Restore02"}]

  • To return a list of restore and replica plans, send the following request:

    GET https://uwin2012r2.n.local:9898/api/v7.21/Plans?filter=[{"property":"planType","operator":"in","value":["Restore","Replica"]}]

    -OR-

    GET https://uwin2012r2.n.local:9898/api/v7.21/Plans?filter=[{"property":"planType","operator":"!=","value":"Storage"}]

  • To return a list of restore plans with the successfully completed readiness check, send the following request:

    GET https://uwin2012r2.n.local:9898/api/v7.21/Plans?filter=[{"operator":"&&", "items":[{"property":"lastCheckResult", "operator":"==","value":"Success"},{"property":"PlanType", "operator":"==", "value":"Restore"}]}]

  • To return a list of plans whose names contain test, send the following request:

    GET https://uwin2012r2.n.local:9898/api/v7.21/Plans?filter=[{"property":"name","operator":"like","value":"test"}]

Sort Parameter

The sort query parameter is used to sort items in a resource collection to be returned in a response.

The parameter accepts the array data type. To sort a resource collection use the sort query parameter in the following format:

GET https://<FQDN>:<port>/api/<version>/Endpoint?sort=[{"property":"<property>","direction":"<direction>"}]

where:

  • <property> is a resource property name.
  • <direction> is a direction specifier.

The Orchestrator 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.

Examples

  • To sort plans by their state, send the following request:

    GET https://uwin2012r2.n.local:9898/api/v7.21/Plans?sort=[{"property":"state","direction":"ASC"}]

  • To sort recovery locations by their type and name, send the following request:

    GET https://uwin2012r2.n.local:9898/api/v7.21/RecoveryLocations?sort=[{"property":"type","direction":"ASC"},{"property":"name","direction":"ASC"}]

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 plans in the /Plans collection, send the following request:

GET https://uwin2012r2.n.local:9898/api/v7.21/Plans?limit=3

The Orchestrator REST API returns resources in the default order based on its own semantics. To sort or filter a collection before selecting top results, use the sort or filter query parameters. Note that the sort 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.

Start Parameter

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

For example, to return a list of recovery locations starting from the forth one in the /RecoveryLocations collection, send the following request:

GET https://uwin2012r2.n.local:9898/api/v7.21/RecoveryLocations?start=3

You can combine the limit and the start query parameters to request a particular set of items. Note that the start 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 Orchestrator 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 or filter query parameters. Note that the sort and filter parameters are applied before the start parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are excluded.

Evaluation with Swagger UI

To start working with the Orchestrator REST API, you can use any client application that supports the HTTPS protocol.

The Orchestrator REST API is additionally available through the Swagger UI, a tool that you can use to evaluate and explore capabilities of the Orchestrator 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 Orchestrator REST API, in a web browser, navigate to the following URL:

https://<FQDN>:<port>/swagger

where:

  • <FQDN> is a DNS name or IP address of the machine where the Orchestrator server runs.

  • <port> is the Web UI port number specified during Orchestrator installation.

    The default port number is 9898.

Welcome to Veeam Recovery Orchestrator REST API

Accessing Swagger UI

To access the Swagger UI for the Orchestrator REST API:

  1. At the top right corner of the Veeam Recovery Orchestrator REST API 7.21 page, click Authorize.

    Getting Authorization

    The Available authorizations window will open.

  2. In the OAuth-credentials section, enter credentials of an account with the Orchestrator Administrator, Plan Author or Plan Operator privileges, and click Authorize.

    The user name must be specified in the DOMAIN\USERNAME or USERNAME format.

    TIP

    If you have already obtained an access token, you can log in to the Swagger UI using this token. To do that, enter the access token in the Value field of the OAuth-token section and click Authorize.

    Available Authorizations

Logging Out

To log out of the Swagger UI, at the top right corner of the Veeam Recovery Orchestrator REST API 7.21 page, click Authorize. In the Available authorizations window, click Logout.

Logging Out

Authorization Examples

The Swagger UI allows a user to try the following Orchestrator REST API authorization procedures:

Obtaining Authorization Tokens

To obtain an access token and a refresh token:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand the Token resource and click POST /api/token.

  2. 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 an account with the Orchestrator Administrator or Plan Author privileges. The user name must be specified in the DOMAIN\USERNAME or USERNAME format.

  5. Click Execute.

    Getting Authorization Token

    Wait for the response from the server. A successfully completed operation returns the 200 response code. In the response body, Orchestrator returns an access token (and its expiration time), a refresh token and an MFA token (and its expiration time).

    IMPORTANT

    For Orchestrator to return an MFA token, MFA must be enabled in the Web UI as described in the Veeam Recovery Orchestrator User Guide, section Enabling and Disabling Multi-Factoring Authentication. However, keep in mind that you will not be able to authorize using the obtained token unless you configure MFA either in the Web UI or in the REST API as described in section Configuring MFA.

    Getting Authorization Token — Server Response

  6. Save the refresh and MFA tokens locally for further use.

Creating Clients

To create a client account:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand the Clients resource and click POST /api/v7.21/Clients.

  2. Click Try it out and then click Execute.

    Getting Child Client

    Wait for the response from the server. A successfully completed operation returns the 200 response code. In the response body, Orchestrator returns a client ID and client secret.

  3. Save the child client ID and client secret locally for further use.

NOTE

Clients cannot create new client accounts.

Obtaining Authorization Tokens Under Client Account

To obtain an access token and a refresh token using client credentials:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand the Token resource and click POST /api/token.

  2. Click Try it out.

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

  4. In the client_id and client_secret fields, specify credentials of a client account.

  5. Click Execute.

    Getting Tokens for Child Client

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

  6. Save the refresh token locally for further use.

Using Refresh Token

To obtain a new pair of tokens using a refresh token:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand the Token resource and click POST /api/token.

  2. From the grant_type drop-down list, select refresh_token.

  3. In the refresh_token field, insert the refresh token saved locally.

  4. Click Execute.

    Using Refresh Token

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

Using MFA Token

To obtain a new pair of tokens using an MFA token:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand the Token resource and click POST /api/token.

  2. Click Try it out.

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

  4. In the mfa_token field, insert the MFA token saved locally.

  5. In the mfa_passcode field, insert the temporary six-digit code generated by an authentication application running on a trusted device.

  6. Click Execute.

    Using MFA Token

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

Sending Requests

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

To send a request:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand a resource to which you want to perform an operation.

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

  3. Click Try it out.

  4. In the expanded method window, enter parameter values.

  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.

Configuring MFA

To configure MFA for a user:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand the Mfa resource and click POST /v7.21/Mfa/GenerateMfaCode.

  2. Click Try it out.

  3. Enter the MFA token you saved locally and then click Execute.

    Configuring MFA

    Wait for the response from the server. A successfully completed operation returns the 200 response code. In the response body, Orchestrator returns an MFA secret code and a URL that can be used to set up your authentication application.

    Configuring MFA — Server Response

  4. Install a supported authentication application on a trusted device. Note that only Google Authenticator and Microsoft Authenticator are fully supported by Orchestrator.

  5. Open the authentication application, choose Add account > Other, click Enter code manually and specify the secret code that you obtained at step 3.

    Alternatively, you can use the URL obtained at step 3 to create a QR code in any QR code generator — and then scan the created code with the camera of the trusted device to complete the MFA configuration process.

Getting Clients

To get all client IDs related to a user account:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand the Clients resource and click GET /api/v7.21/Clients.

  2. Click Try it out and then click Execute.

    Getting Client IDs

    Wait for the response from the server. A successfully completed operation returns the 200 response code and a list of client IDs in the response body.

NOTE

A client can get only its own client ID.

Deleting Clients

To delete a client account:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand the Clients resource and click DELETE /api/v7.21/Clients.

  2. Click Try it out.

  3. In the clientId field, insert the ID of the client that you want to delete.

  4. Click Execute.

    Deleting Client

    Wait for the response from the server. A successfully completed operation returns the 204 response code.

NOTE

A user can delete all related client accounts. A client can delete only his own client account.

Logging Out

To log out from the Orchestrator REST API:

  1. On the Veeam Recovery Orchestrator REST API 7.21 page, expand the Token resource and click DELETE /api/token.

  2. Click Try it out and then click Execute.

    Logging Out

    Wait for the response from the server. A successfully completed operation returns the 204 response code.