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.
Requesting client authorization.
Getting a list of all created clients.
Deleting clients.

Creating Clients

To create a client account, a user sends the HTTP POST request to the api/v7.2/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 List of Created Clients

To get all client IDs related to a user account, the user sends the HTTP GET request to the api/v7.2/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.