Veeam Backup & Replication 10
Veeam RESTful API Reference
Related documents

HTTP Authentication

Every work cycle with Veeam Backup Enterprise Manager RESTful API must begin with the client logon. The logon procedure includes the following steps:

  1. The client sends an unauthorized GET HTTP request to the base URL of Veeam Backup Enterprise Manager RESTful API:
  2. In the response body, the server returns links for creating a new logon session:

Request:

GET https://localhost:9398/api/

 

Response:

200 Success

 

Response Body:

<EnterpriseManager xmlns="http://www.veeam.com/ent/v1.0">
 <Links>
   <Link Rel="Down" Type="LogonSessionList" Href="https://srv12.tech.local:9398/api/logonSessions" />
   <Link Rel="Create" Type="LogonSession" Href="https://srv12.tech.local:9398/api/sessionMngr/?v=latest" />
 </Links>
 <SupportedVersions>
   <SupportedVersion Name="v1">
     <Links>
       <Link Rel="Create" Type="LogonSession" Href="https://srv12.tech.local:9398/api/sessionMngr/?v=v1" />
     </Links>
   </SupportedVersion>
   <SupportedVersion Name="v1_1">
     <Links>
       <Link Rel="Create" Type="LogonSession" Href="https://srv12.tech.local:9398/api/sessionMngr/?v=v1_1" />
     </Links>
   </SupportedVersion>
   <SupportedVersion Name="v1_2">
     <Links>
       <Link Rel="Create" Type="LogonSession" Href="https://srv12.tech.local:9398/api/sessionMngr/?v=v1_2" />
     </Links>
   </SupportedVersion>
   <SupportedVersion Name="v1_3">
     <Links>
       <Link Rel="Create" Type="LogonSession" Href="https://srv12.tech.local:9398/api/sessionMngr/?v=v1_3" />
     </Links>
   </SupportedVersion>
   <SupportedVersion Name="v1_4">
     <Links>
       <Link Rel="Create" Type="LogonSession" Href="https://srv12.tech.local:9398/api/sessionMngr/?v=v1_4" />
     </Links>
   </SupportedVersion>
   <SupportedVersion Name="v1_5">
     <Links>
       <Link Rel="Create" Type="LogonSession" Href="https://srv12.tech.local:9398/api/sessionMngr/?v=v1_5" />
     </Links>
   </SupportedVersion>
 </SupportedVersions>
</EnterpriseManager>

  1. The client sends the POST HTTP requests to the obtained URL to create a new logon session.

In the header of the POST HTTP request, the client must provide the username and password of the account to be used for authentication. The account must have one of the following roles in Veeam Backup Enterprise Manager:

  • Portal Administrators
  • Portal Users
  • Restore Operators

For logon, Veeam Backup Enterprise Manager RESTful API uses the Basic HTTP Authentication. For example, if the client uses the account with the following credentials:

  • Username: User
  • Password: Password

the client must compose the User:Password base64 encoded:

VXNlcjpQYXNzd29yZA==

The Username:Password pair is supplied in the Authorization header to the POST HTTP request. In the value of the header, the client must prepend Basic before the Username:Password pair:

Authorization: Basic VXNlcjpQYXNzd29yZA==

  1. The server analyses the provided credentials and checks if the specified account has the Portal Administrator, Portal User or Restore Operator role in Veeam Backup Enterprise Manager.
  • If the provided credentials are valid and logon has been successful, the server creates a new authentication token and returns it to the client with a representation of a new logon session.
  • If the provided credentials are not valid or the Authentication header is missing, the server returns a 401 Unauthorized error in response. The server also returns the WWW-Authenticate header indicating the authorization scheme to be used, for example:

WWW-Authenticate: Basic Realm=RestSvc

  1. If logon was successful, the server returns the created authentication token in the X-RestSvcSessionId header of the response. The client must obtain the returned authentication token and add it to the header of every subsequent request to the server.

X-RestSvcSessionId: OsU6RL7OGkGKrPBGxKxURw==

In addition, Veeam Backup Enterprise Manager RESTful API returns the cookie token in the Set-Cookie header of the response. The cookie token is kept in the client. If HTTP cookies are enabled for the client, the client can automatically take the authentication token from the cookie and add it to every request to Veeam Backup Enterprise Manager RESTful API.

Set-Cookie: X-RestSvcSessionId=OsU6RL7OGkGKrPBGxKxURw==; Path=/api;

If the client is set to send the authentication token both from the HTTP header and from the cookie, Veeam Backup Enterprise Manager RESTful API will use the cookie token and ignore the token sent in the X-RestSvcSessionId header of the request.

Timeout Value for Idle Sessions

The timeout value for an idle logon session is 15 minutes. If the client sends no requests to the server for 15 minutes, the current session token expires. To continue working with Veeam Backup Enterprise Manager RESTful API, the client must obtain a new authentication token from the server.

Logout

To log out, the client must delete a created logon session. A URL for a session deletion is provided in the representation of the logon session resource:

<Link Rel="Delete" Type="LogonSession" Href="https://localhost:9398/api/logonSessions/d4130a8b-3f5a-4999-8a33-b02c7ff4b441" />

 

HTTP Authentication Tip:

For an example of the logon and logout procedures, see Beginner Example.

 

This Document Help Center
User Guide for VMware vSphereUser Guide for Microsoft Hyper-VVeeam Backup Enterprise Manager GuideVeeam Agent Management GuideVeeam Cloud Connect GuideVeeam Explorers User GuideVeeam Plug-ins for Enterprise Applications GuideVeeam PowerShell ReferenceVeeam Explorers PowerShell ReferenceVeeam RESTful API ReferenceRequired Permissions for VMware vSphereQuick Start Guide for VMware vSphereQuick Start Guide for Microsoft Hyper-VVeeam Backup for AWS DocumentationVeeam Availability for Nutanix AHV DocumentationVeeam Backup for Microsoft Office 365 DocumentationVeeam ONE DocumentationVeeam Agent for Windows DocumentationVeeam Agent for Linux DocumentationVeeam Management Pack Documentation
I want to report a typo

There is a misspelling right here:

 

I want to let the Veeam Documentation Team know about that.