Authorization for Veeam Backup for Microsoft 365 Administrators
To perform all tasks to manage Veeam Backup for Microsoft 365 and backup infrastructure using REST API, the Veeam Backup for Microsoft 365 administrators must authenticate themselves. Veeam Backup for Microsoft 365 REST API authorization process is based on the OAuth 2.0 Authorization Framework and involves obtaining an access token and refresh token:
- Access token is a string that represents authorization issued to the client. It must be used in all requests during the current REST API session.
- Refresh token is a string that represents authorization granted to the client. It is used to obtain a new access token if the current access token expires or becomes lost.
Along with this pair of tokens, the Veeam Backup for Microsoft 365 REST API server issues an antiforgery token. The antiforgery token is stored in your REST API client, for example — in web browser cookies. It protects an access and refresh tokens during a web browser REST API session. Such protection is required, for example, for the Restore Portal operation.
By default, both an access token and antiforgery tokens are required for the Veeam Backup for Microsoft 365 REST API authorization process. The antiforgery token is also required to obtain a new access token using the refresh token.
You can disable usage of the antiforgery token in the Veeam Backup for Microsoft 365 REST API authorization process. To do this, set the true value for the disable_antiforgery_token parameter. For more information, see Request Authorization Tokens.
Veeam Backup for Microsoft 365 REST API authorization process involves the following procedures:
To obtain a pair of tokens, a client sends the POST HTTPS request to the Veeam Backup for Microsoft 365 REST API token path. The request body must contain credentials for authenticating to the Veeam Backup for Microsoft 365 server.
A successfully completed operation returns the 200 OK response code and an access and refresh tokens in the response body. The client inserts the access token in headers of further requests to the Veeam Backup for Microsoft 365 REST API. The refresh token must be saved locally.
|
For more information on how to authorize your access using a client application, see Example Requests and Responses. Alternatively, you can use Swagger UI. For more information, see Evaluation in Swagger UI. |
To obtain a new pair of tokens in case the access token expires or becomes invalid, the client sends the POST HTTPS request with the refresh token in the request body to the Veeam Backup for Microsoft 365 REST API token path. A successfully completed operation returns the 200 OK response code and a new pair of tokens in the response body.
The given access token expires in 60 minutes once issued.
You can logout manually. To do this, send the POST HTTPS request to the /token/logout endpoint. After you log out, access and refresh tokens are expired. A successfully completed operation returns the 204 No Content response code. For more information, see Log Out.
When the client finishes working with the Veeam Explorer for Microsoft Exchange, Veeam Explorer for Microsoft SharePoint, Veeam Explorer for Microsoft OneDrive for Business or Veeam Explorer for Microsoft Teams, they can stop the restore session manually. Otherwise, the session will be stopped automatically. For more information, see Stop Restore Session.
Example Requests and Responses
The following example illustrates how the client and server communicate using requests and responses.
- To obtain access and refresh tokens, send the POST HTTPS request to the Veeam Backup for Microsoft 365 REST API token path. In the request body, enter the credentials for authenticating to the Veeam Backup for Microsoft 365 server.
Request: POST https://abc.tech.local:4443/v8/token
Content-type: application/x-www-form-urlencoded
Request Body: grant_type=password&username=Administrator&password=PassWord1 |
Wait for the response from the server. A successfully completed operation returns the response code 200 OK.
Response: 200 OK
Response Body: { "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJGREVBOEQ4M0Y2OEIyNjRGREY3OEFGN0FDQ0MyRkI3M0EyNTYxODEiLCJ0eXAiOiJKV1QifQ.eyJ0b2tlblR5cGUiOiJBY2Nlc3MiLCJqdGkiOiI5ODcyODJmMi1lNTAyLTQ2NmItYjg5OC0yZjhiZjJhMmZkNDMiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW5pc3RyYXRvciIsImNyZWRlbnRpYWxLZXkiOiI3ODY5MzYzZC1hMGI0LTQzYTQtYWY2NS05NGY4MTJhMTZhY2EiLCJjcmVkZW50aWFsVHlwZSI6IlVzZXJuYW1lUGFzc3dvcmQiLCJhbnRpZm9yZ2VyeSI6IlRydWUiLCJleHAiOjE3MjMxMzExNTMsImlzcyI6IjEyNy4wLjAuMSJ9.N8TH45jADWm6I_78ri61QOZo9ZdViUZ4C9cllMvsl78lCVNmgQAcbZ7rFhWkTHtVCgMgQkatr-7E1c7oQJMkjnI608Avjp4rGVkjYehpBzQ9dFPnvrrA_Ei74ucERiETCQRRuNStearJ2XLKmPja6CbNIZ6pE-JegEk2gz_zvJ0qYlsoa2_xP78cLFCuQD_O5ODycLNF4l3WRnFkMm8GTbpulArmoK7LoK-v1M7p-18XrXRBhMAq_EONln9630STnANzhUYX0eR7NWpU_-01YdL0zWqXpOByx-Msu66QZBb5wjLPYkWeEtHewpjOO31UYJXfMN7nbZ-nWS728xWxcQ", "refresh_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJGREVBOEQ4M0Y2OEIyNjRGREY3OEFGN0FDQ0MyRkI3M0EyNTYxODEiLCJ0eXAiOiJKV1QifQ.eyJ0b2tlblR5cGUiOiJSZWZyZXNoIiwianRpIjoiOTg3MjgyZjItZTUwMi00NjZiLWI4OTgtMmY4YmYyYTJmZDQzIiwiaHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcvd3MvMjAwNS8wNS9pZGVudGl0eS9jbGFpbXMvbmFtZSI6IkFkbWluaXN0cmF0b3IiLCJjcmVkZW50aWFsS2V5IjoiNzg2OTM2M2QtYTBiNC00M2E0LWFmNjUtOTRmODEyYTE2YWNhIiwiY3JlZGVudGlhbFR5cGUiOiJVc2VybmFtZVBhc3N3b3JkIiwiYW50aWZvcmdlcnkiOiJUcnVlIiwiZXhwIjoxNzIzMTM0NzUzLCJpc3MiOiIxMjcuMC4wLjEifQ.EBbhHDhyoO2NMdma2V4G9nue2QWQPQLt7lMM2YrAmjtTxA7QysJEi7P08cqQOo0Gk12FQsTxx-0s_BvpG6FRXwrN7Y409SIP26VdbQJ8Qx2ctkHhtR4CnBJDv6Td9EuOCPK7VHZ7WUkK1_rmmn6VT4u4vtKLMoFAg5kxQg_57VCL9eF73FzJLZRvW-TJPd2egJbI0ReW4Ujlx1BOhape_iZ0gDMLmD5-vfVzZLaxDIhZFgfR4QDUykh0R7pwb4qZO68uQ6vvAwzjy5X7V5Giw7DTE6dvDYoFY8sphsy-GlHJofcvG_lJ8meAdc5LwIsLgN2vwsWdotPb2pK8deeoRw", "token_type": "bearer", "expires_in": 3600, "userName": "Administrator", ".issued": "2024-08-07T15:56:22.9188632Z", ".expires": "2024-08-07T16:56:22.9188632Z" } |
The response body contains access and refresh tokens. Copy both tokens, insert an access token in headers of further requests. A refresh token must be saved locally.
- When an access token expires you can either obtain it again or renew using a refresh token. To renew the access token, send the POST HTTPS request to the Veeam Backup for Microsoft 365 REST API token path. In the request body, enter the refresh token.
Request: POST https://abc.tech.local:4443/v8/token
Request Body: grant_type=refresh_token&refresh_token=<refresh_token> |
Wait for the response from the server. A successfully completed operation returns response code 200 OK and a new pair of tokens in the response body.