Veeam User Management API Guide

Auth method: OAuth 2.0 (Bearer token via /api/oauth2/token password-grant or authorization_code flow)

Setup steps

1. Ensure Veeam Backup & Replication v12+ is installed and the REST API service is running on port 9419.
2. Create a local or domain account in VBR with appropriate role (e.g., Veeam Backup Administrator).
3. POST credentials to /api/oauth2/token with grant_type=password, username, and password to receive an access_token and refresh_token.
4. Include the access_token as 'Authorization: Bearer ' in all subsequent API requests.
5. Tokens expire; use the refresh_token with grant_type=refresh_token to obtain a new access_token without re-authenticating.

Required scopes

Obtain OAuth2 Token

• Method: POST
• URL: https://<vbr-server>:9419/api/oauth2/token
• Watch out for: Token TTL is 900 seconds (15 min) by default. Implement refresh_token logic to avoid re-authentication loops.

Request example

POST /api/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=admin&password=P%40ssw0rd

Response example

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "def50..."
}

List Users

• Method: GET
• URL: https://<vbr-server>:9419/api/v1/users
• Watch out for: Returns only users added to VBR RBAC; does not enumerate all OS-level accounts.

Request example

GET /api/v1/users?skip=0&limit=100
Authorization: Bearer <token>

Response example

{
  "data": [
    {"id": "uuid", "username": "DOMAIN\\jdoe", "roleId": "uuid", "roleName": "Veeam Backup Operator", "accountType": "ActiveDirectory"}
  ],
  "pagination": {"total": 42, "count": 100, "skip": 0}
}

Get User by ID

• Method: GET
• URL: https://<vbr-server>:9419/api/v1/users/{userId}
• Watch out for: Returns 404 if the userId does not exist in VBR RBAC.

Request example

GET /api/v1/users/3fa85f64-5717-4562-b3fc-2c963f66afa6
Authorization: Bearer <token>

Response example

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "username": "DOMAIN\\jdoe",
  "roleId": "uuid",
  "roleName": "Veeam Restore Operator",
  "accountType": "ActiveDirectory"
}

Add User

• Method: POST
• URL: https://<vbr-server>:9419/api/v1/users
• Watch out for: The domain account must already exist in Active Directory; VBR does not create OS accounts.

Request example

POST /api/v1/users
Authorization: Bearer <token>
Content-Type: application/json

{"username": "DOMAIN\\jdoe", "roleId": "<roleUUID>", "accountType": "ActiveDirectory"}

Response example

{
  "id": "new-uuid",
  "username": "DOMAIN\\jdoe",
  "roleId": "<roleUUID>",
  "roleName": "Veeam Restore Operator",
  "accountType": "ActiveDirectory"
}

Update User Role

• Method: PUT
• URL: https://<vbr-server>:9419/api/v1/users/{userId}
• Watch out for: Only roleId can be updated; username and accountType are immutable after creation.

Request example

PUT /api/v1/users/3fa85f64-5717-4562-b3fc-2c963f66afa6
Authorization: Bearer <token>
Content-Type: application/json

{"roleId": "<newRoleUUID>"}

Response example

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "username": "DOMAIN\\jdoe",
  "roleId": "<newRoleUUID>",
  "roleName": "Veeam Backup Administrator"
}

Delete User

• Method: DELETE
• URL: https://<vbr-server>:9419/api/v1/users/{userId}
• Watch out for: Deletes the VBR RBAC entry only; does not disable or remove the underlying OS/AD account.

Request example

DELETE /api/v1/users/3fa85f64-5717-4562-b3fc-2c963f66afa6
Authorization: Bearer <token>

Response example

HTTP 204 No Content

List Roles

• Method: GET
• URL: https://<vbr-server>:9419/api/v1/roles
• Watch out for: Roles are predefined by Veeam; custom roles cannot be created via the REST API.

Request example

GET /api/v1/roles
Authorization: Bearer <token>

Response example

{
  "data": [
    {"id": "uuid", "name": "Veeam Backup Administrator"},
    {"id": "uuid", "name": "Veeam Restore Operator"}
  ]
}

• Rate limits: No explicit rate limit documentation found in official Veeam REST API docs as of v12.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: Official documentation does not publish rate limit values or headers. Practical limits are governed by server resources.

• Pagination method: offset

• Default page size: 100

• Max page size: 500

• Pagination pointer: skip / limit

• Webhooks available: No

• Webhook notes: Veeam Backup & Replication REST API v12 does not expose a native webhook subscription mechanism for user management events.

• Alternative event strategy: Use Veeam ONE REST API or Veeam Backup & Replication notification/alarm system for event-driven monitoring. Polling GET /api/v1/users on a schedule is the supported alternative.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Premium (Enterprise tier, ~$450/workload VUL)

• Endpoint: Not documented

• Supported operations: Create User, Update User, Deactivate User, List Users, Group Push

Limitations:

• SCIM endpoint URL is IdP-generated and configured within the identity provider (e.g., Okta, Azure AD) connector; Veeam does not publish a static universal SCIM base URL.
• Requires Premium (Enterprise) tier licensing.
• SCIM provisioning scope is limited to VBR RBAC user entries; does not provision OS-level accounts.
• Official documentation on specific SCIM attribute mappings is sparse; refer to IdP-specific Veeam app connector documentation.

Three primary automation scenarios are supported by the current API surface:

Onboard an AD user as Restore Operator: POST /api/oauth2/token → GET /api/v1/roles to resolve the Restore Operator UUID → POST /api/v1/users with {username: 'DOMAIN\\user', roleId: '<uuid>', accountType: 'ActiveDirectory'}.

The AD account must pre-exist;

VBR returns an error if directory resolution fails.

Promote a user to Backup Administrator: GET /api/v1/users to locate the user's UUID → GET /api/v1/roles for the Administrator role UUID → PUT /api/v1/users/{userId} with {roleId: '<adminUUID>'}.

Only roleId is mutable post-creation;

username and accountType are immutable.

Offboard a user from VBR RBAC: GET /api/v1/users?skip=0&limit=500, filter by username → DELETE /api/v1/users/{userId}, confirm HTTP 204.

Directory-level deprovisioning (AD disable/delete) must be executed independently - the DELETE call touches only the VBR RBAC entry.

Onboard a new AD user with Restore Operator role

1. POST /api/oauth2/token to obtain Bearer token.
2. GET /api/v1/roles to retrieve the UUID for 'Veeam Restore Operator'.
3. POST /api/v1/users with body {username: 'DOMAIN\newuser', roleId: '', accountType: 'ActiveDirectory'}.
4. Confirm 201 response and store returned user id for future updates.

Watch out for: The AD account must pre-exist; VBR will return an error if the account cannot be resolved in the directory.

Promote a user to Backup Administrator

1. GET /api/v1/users to find the target user's id.
2. GET /api/v1/roles to retrieve the UUID for 'Veeam Backup Administrator'.
3. PUT /api/v1/users/{userId} with body {roleId: ''}.
4. Verify updated roleName in the 200 response.

Watch out for: Only roleId is mutable; attempting to change username or accountType will result in an error.

Offboard a user from VBR RBAC

1. GET /api/v1/users?skip=0&limit=500 and filter by username to locate the user's id.
2. DELETE /api/v1/users/{userId}.
3. Confirm HTTP 204 No Content response.
4. Separately disable or remove the AD/OS account through your identity management system - VBR DELETE does not touch the directory account.

Watch out for: Deleting the VBR RBAC entry does not prevent the user from authenticating to the OS or other systems; directory-level deprovisioning must be handled independently.

The most consequential caveat in this API is the hard boundary between VBR RBAC and the underlying identity layer. Deleting a user via DELETE /api/v1/users/{userId} removes their Veeam console access but leaves the AD or OS account fully intact and authenticable.

Any automation pipeline that treats the VBR DELETE as a complete offboard will leave orphaned credentials in the directory. Additionally, Veeam publishes no rate limit values or retry headers for the REST API - practical throughput is bounded by server resources, making bulk operations unpredictable without empirical testing.

The self-signed TLS certificate on port 9419 requires explicit trust configuration in production clients; disabling TLS verification is acceptable only in isolated dev environments.

Finally, roles are predefined and immutable via the API - there is no endpoint to create or modify role definitions, and SCIM provisioning scope is limited to VBR RBAC entries, not OS accounts.