Authorization and Security

To start working with Veeam ONE REST API, clients must first authenticate themselves. Veeam ONE 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 must be used in all requests during the current logon session.
Refresh token is a string that represents authorization granted to the client and can be used to obtain a new access token when the current access token expires.

Veeam ONE REST API authorization process involves the following procedures:

Requesting Authorization

To obtain a pair of tokens, the client sends the HTTP POST request to the /api/token path.

Authorization and Security Note:

Simultaneous sessions initiated in different client applications under the same user credentials may interfere with each other. To avoid unexpected logout, use a different user account for every application.

A successfully completed operation returns the 200 Success response code and an access and a refresh token in the response body. The client inserts the access token in headers of further requests to Veeam ONE REST API. The refresh token must be saved locally.

Authorization and Security Tip:

To learn how to authorize your access using a client application, you can review the Example Requests and Responses section. Alternatively, you can use Swagger UI.

Using Refresh Token

To obtain a new pair of tokens in case the access token expires or becomes invalid, the client sends the POST HTTP request with the refresh token in the request body to the /api/token path. A successfully completed operation returns the 200 Success response code and a new pair of tokens in the response body.

Performing Logout

When the client finishes working with Veeam ONE REST API, he logs out by sending the POST HTTP request with the access token to the /api/revoke path. A successfully completed operation returns the 200 Success response code.

Example Requests and Responses

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

To obtain an access and a refresh token, send the HTTP POST request to the /api/token path.

In the body of the request, specify the following parameters in the application/x-www-form-urlencoded or multipart/form-data format:

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, one-srv\administrator and Password1 are used.

Request:

POST https://one-srv:1239/api/token

Request Header:

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

Request Body:

grant_type : password

username : one-srv\administrator

password : Password1

The server sends a response in the following format.

Response Code:

200 Success

Response Body:

{

"access_token": "eyJhbGciOiJIUzI1NiIsImtpZCI6IldlYkFwaVNlY3VyaXR5S2V5IiwidHlwIjoiSldUIn0.eyJ1bmlxdWVfbmFtZSI6IklJLVYwMTEtMlxcQWRtaW5pc3RyYXRvciIsInJvbGUiOiJBZG1pbiIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL3NpZCI6IlMtMS01LTIxLTQyOTA5MTM0ODQtMTAzNDIyNjA4Ny03MzA0MjcyODQtNTAwIiwiQWNjZXNzVG9rZW5JZCI6IAFhYjkzYjllLWRhMWYtNDQxOC1hOWUzLTJlOGQxZDU4NDJlZiIsIlVzZXJJZCI6IjIiLCJuYmYiOjE2MDgyMTM1NTQsImV4cCI6MTYwODIxNDQ1MywiaWF0IjoxNjA4MjEzNTUzfQ.9ctZVlohJHJXx_XnF7VhzX_lMoZMCKahC_8cRKlYCQc",

"refresh_token": "523cf7a168ac46b3bc4f884570f7bb5c",

"token_type": "Bearer",

"expires_in": 899,

"user": "ONE-SRV\\Administrator",

"user_role": "Admin"

}

To refresh a pair of tokens, send the HTTP POST request to the /api/token path.

In the body of the request, specify the following parameters in the application/x-www-form-urlencoded or multipart/form-data format:

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://one-srv:1239/api/token

Request Header:

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

Request Body:

grant_type : refresh_token

refresh_token : 523cf7a168ac46b3bc4f884570f7bb5c

To log out, send the HTTP POST request to the /api/revoke path.

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

In the body of the request, specify either of the following parameters in the application/x-www-form-urlencoded or multipart/form-data format:

token — currently valid access token.

UserSid — SID assigned to your user.

Note that if you choose to log out using the token parameter, only the specified token will be revoked. If you have obtained other tokens, they remain active.

Request:

POST https://localhost:1239/api/revoke

Request Header:

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

Authorization: Bearer

Request Body:

token : eyJhbGciOiJIUzI1NiIsImtpZCI6IldlYkFwaVNlY3VyaXR5S2V5IiwidHlwIjoiSldUIn0.eyJ1bmlxdWVfbmFtZSI6IklJLVYwMTEtMlxcQWRtaW5pc3RyYXRvciIsInJvbGUiOiJBZG1pbiIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL3NpZCI6IlMtMS01LTIxLTQyOTA5MTM0ODQtMTAzNDIyNjA4Ny03MzA0MjcyODQtNTAwIiwiQWNjZXNzVG9rZW5JZCI6IAFhYjkzYjllLWRhMWYtNDQxOC1hOWUzLTJlOGQxZDU4NDJlZiIsIlVzZXJJZCI6IjIiLCJuYmYiOjE2MDgyMTM1NTQsImV4cCI6MTYwODIxNDQ1MywiaWF0IjoxNjA4MjEzNTUzfQ.9ctZVlohJHJXx_XnF7VhzX_lMoZMCKahC_8cRKlYCQc