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