Hypervisor Users Api Create Hypervisor User

Hypervisor Users Api Create Hypervisor User
Create a Hypervisor MFA User

Creates a user in state PENDING (ADMIN). 400 INVALID_HYPERVISOR_USER; 409 DUPLICATE_USERNAME when the canonical name already exists (case-insensitive).

Request
URI
POST
https://{api_host}/api/v1/hypervisor-users
COPY
Request Body

The new user: username, optional displayName and email, identitySource (LOCAL when left out) and realm. The user is created in state PENDING.

CreateHypervisorUserRequest of type(s) application/json
Required  

Show optional properties

{
    "username": "string",
    "identitySource": "string"
}
{
    "username": "alice.example",
    "displayName": "Alice Example",
    "email": "[email protected]",
    "identitySource": "LOCAL"
}
string
username
Required  

1-64 characters of letters, digits, dot, underscore or hyphen. For ACTIVE_DIRECTORY the same user part, optionally qualified as DOMAIN\user, user@domain or DOMAIN/user with a domain equal to realm (case-insensitive)

string
displayName
Optional
Constraints: maxLength: 128

Optional display name; more than 128 characters or any control character is rejected with 400 INVALID_HYPERVISOR_USER, and a blank value is stored as null

string
email
Optional
Constraints: maxLength: 254

Optional email address in the form [email protected] without spaces; an invalid or longer than 254 characters address is rejected with 400 INVALID_HYPERVISOR_USER, and a blank value is stored as null

string
identitySource
Required  

SHARED_ROOT_PRINCIPAL: OS login is root and the person types a Console username at the second prompt. LOCAL: a named local account. ACTIVE_DIRECTORY: an AD account; a realm is required.

  • SHARED_ROOT_PRINCIPAL: The canonical name is the name as entered (case kept, 1 to 64 letters, digits, dot, underscore or hyphen); a realm is refused, and the bare name root is refused
  • LOCAL: The canonical name is the name as entered (case kept, 1 to 64 letters, digits, dot, underscore or hyphen); a realm is refused, and the bare name root is refused
  • ACTIVE_DIRECTORY: A realm is required; the canonical name is lowercase, as user@domain when the realm contains a dot and as domain, backslash and user otherwise, or in the qualified form that was entered
Enumeration: SHARED_ROOT_PRINCIPAL, LOCAL, ACTIVE_DIRECTORY
string
realm
Optional

Required for ACTIVE_DIRECTORY (NetBIOS or DNS domain name); refused for the other sources

Authentication
This operation uses the following authentication methods.
Responses
201

201 Created successful response envelope. The created user in state PENDING

Returns HypervisorUserSummaryDto of type(s) application/json
{
    "id": 1,
    "username": "alice.example",
    "canonicalUsername": "alice.example",
    "displayName": "Alice Example",
    "email": "[email protected]",
    "identitySource": "LOCAL",
    "provisioningSource": "MANUAL",
    "enrollmentStatus": "PENDING",
    "enabled": true,
    "secretVersion": 0,
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z"
}
integer As int64 As int64
id
Required  

Identifier of the Hypervisor MFA User, assigned when the record is created

string
username
Required  

The name as entered by the administrator

string
canonicalUsername
Required  

The name the Agent matches an SSH login against: the entered name for SHARED_ROOT_PRINCIPAL and LOCAL, and for ACTIVE_DIRECTORY always lowercase in the form the user logs in with (user@domain, domain, backslash and user, or domain, slash and user)

string
displayName
Optional

Optional display name of at most 128 characters without control characters; null when none was set

string
email
Optional

Optional email address of at most 254 characters; null when none was set

string
identitySource
Required  

SHARED_ROOT_PRINCIPAL: OS login is root and the person types a Console username at the second prompt. LOCAL: a named local account. ACTIVE_DIRECTORY: an AD account; a realm is required.

  • SHARED_ROOT_PRINCIPAL: The canonical name is the name as entered (case kept, 1 to 64 letters, digits, dot, underscore or hyphen); a realm is refused, and the bare name root is refused
  • LOCAL: The canonical name is the name as entered (case kept, 1 to 64 letters, digits, dot, underscore or hyphen); a realm is refused, and the bare name root is refused
  • ACTIVE_DIRECTORY: A realm is required; the canonical name is lowercase, as user@domain when the realm contains a dot and as domain, backslash and user otherwise, or in the qualified form that was entered
Enumeration: SHARED_ROOT_PRINCIPAL, LOCAL, ACTIVE_DIRECTORY
string
realm
Optional

Present exactly when identitySource is ACTIVE_DIRECTORY

string
provisioningSource
Required  

How a Hypervisor MFA User record was created.

  • MANUAL: Created by the create operation
  • CSV_IMPORT: Created by the CSV import
Enumeration: MANUAL, CSV_IMPORT
string
enrollmentStatus
Required  

PENDING: no secret issued. ENROLLED: a secret is issued. REVOKED: every secret version is destroyed.

  • PENDING: The initial status; also set again when cancelling the first enrollment; only a PENDING user can be enrolled
  • ENROLLED: An enrollment was issued by enroll or re-enroll; also restored when cancelling a re-enroll returns to the previous enrollment
  • REVOKED: The revoke operation was applied; also set when cancelling a re-enroll finds no previous enrollment to restore
Enumeration: PENDING, ENROLLED, REVOKED
boolean
enabled
Required  

Whether the user is enabled; a new user starts enabled and the update operation changes it

integer As int32 As int32
secretVersion
Required  

Current secret version; 0 while PENDING

string As date-time As date-time
enrolledAt
Optional

Time the current MFA enrollment was issued by enroll or re-enroll; null while no enrollment has been issued, and again after the first enrollment is cancelled

string As date-time As date-time
createdAt
Required  

Time the user record was created

string As date-time As date-time
updatedAt
Required  

Time the user record was last changed


400

400 Bad Request: INVALID_HYPERVISOR_USER when a field is missing or not valid, such as an unknown identitySource, a displayName that is too long or an email that is not a valid address; MALFORMED_REQUEST when the body cannot be read

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: FORBIDDEN when the signed-in role is not allowed to call this operation; CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)

Returns ForbiddenWrite of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


409

409 Conflict: DUPLICATE_USERNAME when the canonical username already exists, compared without regard to case

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"username":"string","identitySource":"string"}' https://{api_host}/api/v1/hypervisor-users