Create User

The Create User operation creates a standard or template User object with the given properties. This operation is not valid for system-defined or pattern-based users.

HTTP method and URI

POST /api/console/users

Request body contents

The request body is expected to contain a JSON object with the following fields:

Field name Type Rqd/Opt Description
name String Required The value to be set as the user's name property.

Note that the length and character requirements that apply to this field are dependent on the value of the type field.

description String Optional The value to be set as the user's description property.
type String Enum Required The value to be set as the user's type property. Must be "standard" or "template".
disabled Boolean Optional The value to be set as the user's disabled property.
authentication-type String Enum Required The value to be set as the user's authentication-type property.
password-rule-uri String/ URI Required if authentication-type is "local" The value to be set as the user's password-rule-uri property.
password String Required if authentication-type is "local" The value to be set as the user's password property.
force-password-change Boolean Optional The value to be set as the user's force-password-change property.
ldap-server-definition-uri String/ URI Required if authentication-type is "ldap" The value to be set as the user's ldap-server-definition-uri property.
userid-on-ldap-server String Optional The value to be set as the user's userid-on-ldap-server property.
session-timeout Integer Optional The value to be set as the user's session-timeout property.
verify-timeout Integer Optional The value to be set as the user's verify-timeout property.
idle-timeout Integer Optional The value to be set as the user's idle-timeout property.
min-pw-change-time Integer Optional The value to be set as the user's min-pw-change-time property.
max-failed-logins Integer Optional The value to be set as the user's max-failed-logins property.
disable-delay Integer Optional The value to be set as the user's disable-delay property.
inactivity-timeout Integer Optional The value to be set as the user's inactivity-timeout property.
disruptive-pw-required Boolean Optional The value to be set as the users disruptive-pw-required property.
disruptive-text-required Boolean Optional The value to be set as the user's disruptive-text-required property.
allow-remote-access Boolean Optional The value to be set as the user's allow-remote-access property.
allow-management-interfaces Boolean Optional The value to be set as the user's allow-management-interfaces property.
max-web-services-api-sessions Integer Optional The value to be set as the user's max-web-services-api-sessions property.
web-services-api-session-idle-timeout Integer Optional The value to be set as the user's web-services-api-session-idle-timeout property.
multi-factor-authentication-required Boolean Optional The value to be set as the user's multi-factor-authentication-required property.
mfa-types Array of String Enum Optional The value to be set as the user's mfa-types property.
primary-mfa-server-definition-uri String/ URI Required if mfa-types contains "mfa-server" The value to be set as the user's primary-mfa-server-definition-uri property.
backup-mfa-server-definition-uri String/ URI Optional The value to be set as the user's backup-mfa-server-definition-uri property.
mfa-policy String Required if mfa-types contains "mfa-server" The value to be set as the user's mfa-policy property.
mfa-userid String Optional The value to be set as the user's mfa-userid property.
mfa-userid-override String Optional The value to be set as the user's mfa-userid-override property.

Response body contents

On successful completion, the response body contains a JSON object with the following fields:

Field name Type Description
object-uri String/ URI Canonical URI path of the new User object.

Description

This operation creates a new console user.

On successful execution of this operation the user is created using the inputs as specified by the request body. The URI of the new user is provided in the response body and in a Location response header as well. An Inventory Change notification is emitted asynchronously.

The request body is validated against the schema described in the Request body contents. If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation error encountered. The request body validation will fail if it contains a property that is not valid because a prerequisite is not met (e.g., specifying password-rule-uri when the authentication-type value is "ldap") or the specified name is not unique. If a URI in the request body does not designate an existing resource of the appropriate type, status code 404 (Not Found) is returned. In addition, the API user must have action/task permission to the Manage Users task to create a standard user or the Manage User Templates task to create a template user; otherwise, status code 403 (Forbidden) is returned.

Certain user names are used internally by the Hardware Management Console and are therefore not available for use when creating a new user. An attempt to create a user with one of these names results in status code 400 (Bad Request) indicating that there is already a user with that name. The list of such names is case-insensitive and includes the following:

  • SOOACSADMIN
  • SOOADVANCED
  • SOOENSADMIN
  • SOOENSOPERATOR
  • SOOOPERATOR
  • SOOSERVICE
  • SOOSTORAGEADMIN
  • SOOSYSPROG
  • PEDEBUG

Authorization requirements

This operation has the following authorization requirement:
  • Action/task permission to the Manage Users task to create a standard user or the Manage User Templates task to create a template user.

HTTP status and reason codes

On success, HTTP status code 201 (Created) is returned and the response body is provided as described in Response body contents, and the Location response header contains the URI of the newly created object.

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

Table 1. Create User: HTTP status and reason codes
HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
8 A user with the name specified in the request body already exists.
311 The password does not conform to the requirements of the password policy in effect for this user.
337 The primary-mfa-server-definition-uri in the request body and the backup-mfa-server-definition-uri in the request body designate the same MFA Server Definition object.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 323 The password-rule-uri field in the request body does not designate an existing Password Rule object.
324 The ldap-server-definition-uri field in the request body does not designate an existing LDAP Server Definition object.
338 The primary-mfa-server-definition-uri in the request body does not designate an existing MFA Server Definition object.
339 The backup-mfa-server-definiton-uri in the request body does not designate an existing MFA Server Definition object.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Create User: Request

POST /api/console/users HTTP/1.1
x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 234
{
   "authentication-type":"local",
   "description":"Gabby McRosie - company president",
   "name":"Gabby",
   "password":"abc123pw",
   "password-rule-uri":"/api/console/password-rules/4a790766-3dbf-11e4-980d-1c6f65065a91",
   "type":"standard"
}
Figure 2. Create User: Response
201 Created
server: zSeries management console API web server / 2.0
location: /api/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:29 GMT
content-type: application/json;charset=UTF-8
content-length: 64
{
   "object-uri":"/api/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91"
}