NSX-T Data Center Global Manager REST API

Create node users

Create new user account to log in to the NSX web-based user interface or access API.
username is required field in case of creating new user, further following
usernames - root, admin, audit are reserved and can not be used
to create new user account unless for local audit user.
In case of local audit account when username not specified in request by default
account will be created with audit username, although administrators
are allowed to use any other non-duplicate usernames during creation.


When a VCF password management policy is configured, VCF password management policy's
properties take precedence and are enforced. password_change_frequency is set to the
VCF password management policy's passwordExpirationDays if not provided. Specifying
the password_change_frequency value that conflicts with the VCF password management
policy's passwordExpirationDays returns 409 CONFLICT. Please use the VCF Ops UI/API
to update the policy if needed.

Request:

Method:

POST

URI Path(s):

/api/v1/cluster/{cluster-node-id}/node/users?action=create_user
/api/v1/cluster/{cluster-node-id}/node/users?action=create_audit_user
/api/v1/cluster/{cluster-node-id}/node/users?action=create_service_user
/api/v1/node/users?action=create_user
/api/v1/node/users?action=create_audit_user
/api/v1/node/users?action=create_service_user

Request Headers:

n/a

Query Parameters:

n/a

Request Body:

NodeUserProperties+

NodeUserProperties (schema)

Name	Description	Type	Notes
_links	References related to this resource The server will populate this field when returing the resource. Ignored on PUT and POST.	array of ResourceLink	Readonly
_schema	Schema for this resource	string	Readonly
_self	Link to this resource	SelfResourceLink	Readonly
account_expires	Node local user account expiration date (ISO-8601 date form, i.e. YYYY-MM-DD) or null when never expires	string	Readonly
account_type	Node local user account type	string	Readonly Enum: administrator, audit, guest, root, service, system
full_name	Full name for the user	string
group_id	Primary group id for the user	integer	Readonly Minimum: 0 Maximum: 2147483647
home_dir	The absolute path of user home directory	string	Readonly
last_password_change	Number of days since password was last changed	integer	Readonly Minimum: 0 Maximum: 2147483647
last_password_change_epoch	Node local user account last password change Unix Epoch timestamp or 0 when never changed	integer	Readonly
locked	List indicating user is currently locked out for target interface http when the user account is currently locked to make any web authentication requests, because of many consecutive failed authentication attempts was made for a respective user (at max of configured auth-policy api_failed_auth_lockout_period). cli when the user account is currently locked to make any NSX-CLI authentication requests as per configured cli-lockout policy Property is available only when list node users is issued with query parameter - internal=true, check ListNodeUsers [GET] /api/v1/node/users for more details.	array of string	Readonly
login_shell	The absolute path of login shell	string	Readonly
old_password	Old password for the user (required on PUT if password specified)	string
password	Password for the user (optionally specified on PUT, unspecified on GET)	string
password_change_frequency	Number of days password is valid before it must be changed Number of days password is valid before it must be changed. This can be set to 0 to indicate no password change is required or a positive integer up to 9999. For following account_types - root, administrator, audit, guest, VCF password management policy's passwordExpirationDays will be preferred by default, further overriding in request will error out with 409 CONFLICT. For other account_types, or when no VCF password management policy is configured, the default value is 90.	integer	Minimum: 0 Maximum: 99999 Default: "90"
password_change_warning	Number of days before user receives warning message of password expiration	integer	Minimum: 0 Maximum: 99999 Default: "7"
password_expires	Node local user account password expiration date (ISO-8601 date form, i.e. YYYY-MM-DD) or null when never expires	string	Readonly
password_expires_epoch	Node local user account password expiration Unix Epoch timestamp or 0 when never expires	integer	Readonly
password_reset_required	Boolean value that states if a password reset is required	boolean
status	User status Status of the user. This value can be ACTIVE indicating authentication attempts will be successful if the correct credentials are specified. The value can also be PASSWORD_EXPIRED indicating authentication attempts will fail because the user's password has expired and must be changed. Or, this value can be NOT_ACTIVATED indicating the user's password has not yet been set and must be set before the user can authenticate.	string	Readonly Enum: ACTIVE, PASSWORD_EXPIRED, NOT_ACTIVATED
userid	Numeric id for the user	integer	Readonly Minimum: 0 Maximum: 2147483647
username	User login name (must be "root" if userid is 0)	string	Minimum length: 1 Maximum length: 32 Pattern: "^[a-zA-Z][a-zA-Z0-9-_.\-]*$"

Example Request:

POST https://<nsx-mgr>/api/v1/node/users?action=create_user { "full_name": "New user", "username": "newuser" }

Successful Response:

Response Code:

201 Created

Response Headers:

Content-type: application/json

Response Body:

NodeUserProperties+

NodeUserProperties (schema)

Name	Description	Type	Notes
_links	References related to this resource The server will populate this field when returing the resource. Ignored on PUT and POST.	array of ResourceLink	Readonly
_schema	Schema for this resource	string	Readonly
_self	Link to this resource	SelfResourceLink	Readonly
account_expires	Node local user account expiration date (ISO-8601 date form, i.e. YYYY-MM-DD) or null when never expires	string	Readonly
account_type	Node local user account type	string	Readonly Enum: administrator, audit, guest, root, service, system
full_name	Full name for the user	string
group_id	Primary group id for the user	integer	Readonly Minimum: 0 Maximum: 2147483647
home_dir	The absolute path of user home directory	string	Readonly
last_password_change	Number of days since password was last changed	integer	Readonly Minimum: 0 Maximum: 2147483647
last_password_change_epoch	Node local user account last password change Unix Epoch timestamp or 0 when never changed	integer	Readonly
locked	List indicating user is currently locked out for target interface http when the user account is currently locked to make any web authentication requests, because of many consecutive failed authentication attempts was made for a respective user (at max of configured auth-policy api_failed_auth_lockout_period). cli when the user account is currently locked to make any NSX-CLI authentication requests as per configured cli-lockout policy Property is available only when list node users is issued with query parameter - internal=true, check ListNodeUsers [GET] /api/v1/node/users for more details.	array of string	Readonly
login_shell	The absolute path of login shell	string	Readonly
old_password	Old password for the user (required on PUT if password specified)	string
password	Password for the user (optionally specified on PUT, unspecified on GET)	string
password_change_frequency	Number of days password is valid before it must be changed Number of days password is valid before it must be changed. This can be set to 0 to indicate no password change is required or a positive integer up to 9999. For following account_types - root, administrator, audit, guest, VCF password management policy's passwordExpirationDays will be preferred by default, further overriding in request will error out with 409 CONFLICT. For other account_types, or when no VCF password management policy is configured, the default value is 90.	integer	Minimum: 0 Maximum: 99999 Default: "90"
password_change_warning	Number of days before user receives warning message of password expiration	integer	Minimum: 0 Maximum: 99999 Default: "7"
password_expires	Node local user account password expiration date (ISO-8601 date form, i.e. YYYY-MM-DD) or null when never expires	string	Readonly
password_expires_epoch	Node local user account password expiration Unix Epoch timestamp or 0 when never expires	integer	Readonly
password_reset_required	Boolean value that states if a password reset is required	boolean
status	User status Status of the user. This value can be ACTIVE indicating authentication attempts will be successful if the correct credentials are specified. The value can also be PASSWORD_EXPIRED indicating authentication attempts will fail because the user's password has expired and must be changed. Or, this value can be NOT_ACTIVATED indicating the user's password has not yet been set and must be set before the user can authenticate.	string	Readonly Enum: ACTIVE, PASSWORD_EXPIRED, NOT_ACTIVATED
userid	Numeric id for the user	integer	Readonly Minimum: 0 Maximum: 2147483647
username	User login name (must be "root" if userid is 0)	string	Minimum length: 1 Maximum length: 32 Pattern: "^[a-zA-Z][a-zA-Z0-9-_.\-]*$"

Example Response:

{ "full_name": "New user" "userid": 10009, "username": "newuser", "status": "NOT_ACTIVATED", "password_change_frequency": 90, "password_change_warning": 7 }

Required Permissions:

crud

Feature:

system_administration

Additional Errors:

• 301 Moved Permanently
• 307 Temporary Redirect
• 400 Bad Request
• 403 Forbidden
• 409 Conflict
• 412 Precondition Failed
• 500 Internal Server Error
• 503 Service Unavailable