Veeam Backup & Replication 13
REST API Reference
Related documents

Users and Roles

The Users and Roles section defines operations for managing Veeam Backup & Replication users, groups and assigned roles.

Get All Users and Groups

The HTTP GET request to the /api/v1/security/users endpoint gets an array of users and groups, along with their assigned roles.

Available to: Backup Administrator.

SecurityBearer
Request
query Parameters
skip
integer <int32>

Number of users and groups to skip.

limit
integer <int32>
Default: 200

Maximum number of users and groups to return.

orderColumn
string (EUserFiltersOrderColumn)

Sorts users and groups by one of the parameters.

Enum: "Name" "Type" "IsServiceAccount" "MfaEnabled"
orderAsc
boolean

If true, sorts the results in ascending order by the orderColumn parameter.

nameFilter
string

Filters users and groups by the nameFilter pattern.

typeFilter
Array of strings (EUserType)

Filters users and groups by type.

Items Enum: "InternalUser" "InternalGroup" "ExternalUser" "ExternalGroup"
roleIdFilter
string <uuid>

Filters users by role id.

roleNameFilter
string

Filters users by role name.

isServiceAccountFilter
boolean

If true, returns only users that are service accounts.

header Parameters
x-api-version
required
string
Default: 1.3-rev2

Version and revision of the client REST API. Must be in the following format: <version>-<revision>.

Responses
200

OK

401

Unauthorized. The authorization header has been expected but not found (or found but is expired).

403

Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.

500

Internal server error. The request has been received but could not be completed because of an internal error at the server side.

get/api/v1/security/users
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}
Add User or Group
The HTTP POST request to the /api/v1/security/users endpoint adds a user or group with an assigned built-in role.
Available to: Backup Administrator.


SecurityBearer 
Request 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Request Body schema: application/json
required
name
required
string
User or group name.


 
type
required
string (EUserType) 
User or group type.


 Enum: "InternalUser" "InternalGroup" "ExternalUser" "ExternalGroup"  
required
Array of objects (RoleModel)   non-empty 
Array of roles assigned to the user or group.


 
isServiceAccount
required
boolean
If true, the user or group is a service account.


 
Responses 
201
User or group has been added.


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


post/api/v1/security/users
Request samples 
application/json
{
  • "name": "TECH\\sheila.d.cory",
  • "type": "InternalUser",
  • "roles": [
    ],
  • "isServiceAccount": false
}
Response samples 
application/json
{
  • "id": "1cc300d4-c356-46d6-a1b8-ccd0b23cc08e",
  • "name": "TECH\\sheila.d.cory",
  • "type": "InternalUser",
  • "roles": [
    ],
  • "isServiceAccount": false,
  • "mfaEnabled": true
}
Get User or Group
The HTTP GET request to the /api/v1/security/users/{id} endpoint gets a user or group that has the specified id.
Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
User or group ID. To get the ID, run the Get All Users and Groups request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
200
OK


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


get/api/v1/security/users/{id}
Request samples 
Response samples 
application/json
{
  • "type": "InternalUser",
  • "id": "1cc300d4-c356-46d6-a1b8-ccd0b23cc08e",
  • "name": "TECH\\sheila.d.cory",
  • "roles": [
    ],
  • "isServiceAccount": false,
  • "mfaEnabled": true
}
Remove User or Group
The HTTP DELETE request to the /api/v1/security/users/{id} endpoint removes a user or group that has the specified id.
 Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
User or group ID. To get the ID, run the Get All Users and Groups request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
204
User or group has been removed.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


delete/api/v1/security/users/{id}
Request samples 
Response samples 
application/json
{
  • "errorCode": "AccessDenied",
  • "message": "Unauthorized. Get bearer JWT token at /api/login"
}
Get Roles Assigned to User or Group
The HTTP GET request to the /api/v1/security/users/{id}/roles endpoint gets the roles assigned to a user or group that has the specified id.
Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
User or group ID. To get the ID, run the Get All Users and Groups request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
200
OK


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


get/api/v1/security/users/{id}/roles
Request samples 
Response samples 
application/json
{
  • "roles": [
    ]
}
Edit Roles Assigned to User or Group
The HTTP PUT request to the /api/v1/security/users/{id}/roles endpoint edits the roles assigned to a user or group that has the specified id.
 Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
User or group ID. To get the ID, run the Get All Users and Groups request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Request Body schema: application/json
required
required
Array of objects (RoleModel)   non-empty 
Array of roles assigned to the user or group.


 
Responses 
200
User or group has been updated.


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


put/api/v1/security/users/{id}/roles
Request samples 
application/json
{
  • "roles": [
    ]
}
Response samples 
application/json
{
  • "roles": [
    ]
}
Change Service Account Mode
The HTTP POST request to the /api/v1/security/users/{id}/changeServiceAccountMode endpoint changes the service account mode of a user that has the specified id. Note that MFA will be automatically disabled for the service account.
Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
User ID. To get the ID, run the Get All Users and Groups request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Request Body schema: application/json
required
isServiceAccountEnable
required
boolean
If true, the user or group is a service account.


 
Responses 
200
User or group has been updated.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


post/api/v1/security/users/{id}/changeServiceAccountMode
Request samples 
application/json
{
  • "isServiceAccountEnable": true
}
Response samples 
application/json
{
  • "id": "1cc300d4-c356-46d6-a1b8-ccd0b23cc08e",
  • "name": "TECH\\sheila.d.cory",
  • "type": "InternalUser",
  • "roles": [
    ],
  • "isServiceAccount": false,
  • "mfaEnabled": true
}
Reset MFA for Specific User
The HTTP POST request to the /api/v1/security/users/{id}/resetMFA endpoint resets multi-factor authentication (MFA) for a user that has the specified id. The next time the user logs in, they will be prompted to configure MFA again.
Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
User or group ID. To get the ID, run the Get All Users and Groups request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
204
MFA has been reset.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


post/api/v1/security/users/{id}/resetMFA
Request samples 
Response samples 
application/json
{
  • "errorCode": "AccessDenied",
  • "message": "Unauthorized. Get bearer JWT token at /api/login"
}
Get All Roles
The HTTP GET request to the /api/v1/security/roles endpoint gets an array of roles available in Veeam Backup & Replication.
Available to: Backup Administrator, Backup Operator, Restore Operator. Also available to custom roles that have backup or restore permissions.


SecurityBearer 
Request 
query Parameters
skip
integer <int32> 
Number of roles to skip.


 
limit
integer <int32> 
 Default:  200
Maximum number of roles to return.


 
orderColumn
string (ERolesFiltersOrderColumn) 
Sorts roles by one of the role parameters.


 Enum: "Name" "Description"  
orderAsc
boolean
If true, sorts roles in ascending order by the orderColumn parameter.


 
nameFilter
string
Filters roles by the nameFilter pattern.


 
isBuiltInFilter
boolean
If true, returns only built-in roles. If false, returns only custom roles.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
200
OK


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


get/api/v1/security/roles
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}
Create Custom Role
The HTTP POST request to the /api/v1/security/roles endpoint creates a custom role with tailored permissions and granular access scopes.
Available to: Backup Administrator.


SecurityBearer 
Request 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Request Body schema: application/json
required
name
required
string
Role name.


 
manageBackups
required
boolean
If true, the role can create and manage backup jobs.


 
manageRestores
required
boolean
If true, the role can perform restores from existing backups.


 
description
string
Role description.


 
object (InventoryScopeModel) 
Inventory scope.


 
object (RepositoryScopeModel) 
Repository scope.


 
object (RestorePermissionsScopeModel) 
Restore permissions scope.


 
object (RestoreTargetScopeModel) 
Restore target scope.


 
Responses 
201
Custom role has been created.


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


post/api/v1/security/roles
Request samples 
application/json
{
  • "name": "Restore Operator",
  • "description": "Custom role limited to restore operations",
  • "manageBackups": false,
  • "manageRestores": true,
  • "inventoryScope": {
    },
  • "repositoryScope": {
    },
  • "restorePermissionsScope": {
    },
  • "restoreTargetScope": {
    }
}
Response samples 
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "name": "Custom Restore Operator",
  • "description": "Custom role limited to restore operations",
  • "manageBackups": false,
  • "manageRestores": true,
  • "inventoryScope": {
    },
  • "repositoryScope": {
    },
  • "restorePermissionsScope": {
    },
  • "restoreTargetScope": {
    }
}
Get Role
The HTTP GET request to the /api/v1/security/roles/{id} endpoint gets a role that has the specified id.
Available to: Backup Administrator, Backup Operator, Restore Operator. Also available to custom roles that have backup or restore permissions.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Role ID. To get the ID, run the Get All Roles request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
200
OK


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


get/api/v1/security/roles/{id}
Request samples 
Response samples 
application/json
{
  • "id": "5ff0e0eb-45cf-48cc-9677-7613fc79bc11",
  • "name": "Backup Administrator",
  • "description": "Built-in role with full privileges"
}
Edit Custom Role
The HTTP PUT request to the /api/v1/security/roles/{id} endpoint edits a custom role that has the specified id.
Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Role ID. To get the ID, run the Get All Roles request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Request Body schema: application/json
required
id
required
string <uuid> 
Role ID.


 
name
required
string
Role name.


 
manageBackups
required
boolean
If true, the role can create and manage backup jobs.


 
manageRestores
required
boolean
If true, the role can perform restores from existing backups.


 
description
string
Role description.


 
object (InventoryScopeModel) 
Inventory scope.


 
object (RepositoryScopeModel) 
Repository scope.


 
object (RestorePermissionsScopeModel) 
Restore permissions scope.


 
object (RestoreTargetScopeModel) 
Restore target scope.


 
Responses 
200
Custom role has been updated.


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


put/api/v1/security/roles/{id}
Request samples 
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "name": "Custom Restore Operator",
  • "description": "Custom role limited to restore operations",
  • "manageBackups": false,
  • "manageRestores": true,
  • "inventoryScope": {
    },
  • "repositoryScope": {
    },
  • "restorePermissionsScope": {
    },
  • "restoreTargetScope": {
    }
}
Response samples 
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "name": "Custom Restore Operator",
  • "description": "Custom role limited to restore operations",
  • "manageBackups": false,
  • "manageRestores": true,
  • "inventoryScope": {
    },
  • "repositoryScope": {
    },
  • "restorePermissionsScope": {
    },
  • "restoreTargetScope": {
    }
}
Delete Custom Role
The HTTP DELETE request to the /api/v1/security/roles/{id} endpoint deletes a custom role that has the specified id.
Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Role ID. To get the ID, run the Get All Jobs request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
204
Removed.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


delete/api/v1/security/roles/{id}
Request samples 
Response samples 
application/json
{
  • "errorCode": "AccessDenied",
  • "message": "Unauthorized. Get bearer JWT token at /api/login"
}
Get Role Permissions
The HTTP GET request to the /api/v1/security/roles/{id}/permissions endpoint gets the permissions of a role that has the specified id. 
Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Role ID. To get the ID, run the Get All Roles request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
200
OK


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


get/api/v1/security/roles/{id}/permissions
Request samples 
Response samples 
application/json
{
  • "roleId": "e71bb27e-bd16-47b6-8b1c-98ef2d7a996e",
  • "permissions": [
    ]
}
Get Custom Role Details
The HTTP GET request to the /api/v1/security/roles/{id}/details endpoint gets a custom role that has the specified id. The response includes the permissions, inventory scope, repository scope, restore permissions scope and restore target scope of the custom role.
Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Custom role ID. To get the ID, run the Get All Roles request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
200
OK


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


get/api/v1/security/roles/{id}/details
Request samples 
Response samples 
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "name": "Custom Restore Operator",
  • "description": "Custom role limited to restore operations",
  • "manageBackups": false,
  • "manageRestores": true,
  • "inventoryScope": {
    },
  • "repositoryScope": {
    },
  • "restorePermissionsScope": {
    },
  • "restoreTargetScope": {
    }
}
Clone Custom Role
The HTTP POST request to the /api/v1/security/roles/{id}/clone endpoint clones a custom role that has the specified id. The cloned role has the same permissions and scopes as the original role. The name of the cloned role is {original_name}_Clone.
Available to: Backup Administrator.


SecurityBearer 
Request 
path Parameters
id
required
string <uuid> 
Role ID. To get the ID, run the Get All Roles request.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
201
Custom role has been cloned.


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


404
Not found. No object was found with the path parameter specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


post/api/v1/security/roles/{id}/clone
Request samples 
Response samples 
application/json
{
  • "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  • "name": "Custom Restore Operator_Clone",
  • "description": "Custom role limited to restore operations",
  • "manageBackups": false,
  • "manageRestores": true,
  • "inventoryScope": {
    },
  • "repositoryScope": {
    },
  • "restorePermissionsScope": {
    },
  • "restoreTargetScope": {
    }
}
Get MFA Settings
The HTTP GET request to the /api/v1/security/settings endpoint checks whether multi-factor authentication (MFA) is enabled or disabled for all users.
Available to: Backup Administrator.


SecurityBearer 
Request 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
200
OK


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


get/api/v1/security/settings
Request samples 
Response samples 
application/json
{
  • "mfaEnabled": true
}
Edit MFA Settings
The HTTP PUT request to the /api/v1/security/settings endpoint enables or disables multi-factor authentication (MFA) for all users.
Available to: Backup Administrator.


SecurityBearer 
Request 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Request Body schema: application/json
required
mfaEnabled
boolean
If true,  multi-factor authentication (MFA) is enabled.


 
Responses 
200
OK


400
Bad request. This error is related to POST/PUT requests. The request body is malformed, incomplete or otherwise invalid.


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


put/api/v1/security/settings
Request samples 
application/json
{
  • "mfaEnabled": true
}
Response samples 
application/json
{
  • "mfaEnabled": true
}
Get All Restore Options
The HTTP GET request to the /api/v1/security/restoreOptions endpoint gets an array of restore options.
Available to: Backup Administrator.


SecurityBearer 
Request 
query Parameters
skip
integer <int32> 
Number of restore options to skip.


 
limit
integer <int32> 
 Default:  200
Maximum number of restore options to return.


 
orderColumn
string (ERestoreOptionsFiltersOrderColumn) 
Sorts restore options by one of the restore option parameters.


 Enum: "Code" "Name" "Group" "Description"  
orderAsc
boolean
If true, sorts restore options in ascending order by the orderColumn parameter.


 
codeFilter
string
Filters restore options by the codeFilter pattern.


 
nameFilter
string
Filters restore options by the nameFilter pattern.


 
groupFilter
string
Filters restore options by the groupFilter pattern.


 
header Parameters
x-api-version
required
string
 Default:  1.3-rev2
Version and revision of the client REST API. Must be in the following format: <version>-<revision>.


 
Responses 
200
OK


401
Unauthorized. The authorization header has been expected but not found (or found but is expired).


403
Forbidden. The user sending the request does not have adequate privileges to access one or more objects specified in the request.


500
Internal server error. The request has been received but could not be completed because of an internal error at the server side.


get/api/v1/security/restoreOptions
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}