Create MFA Server Definition

The Create MFA Server Definition operation creates an MFA Server Definition object with the given properties.

HTTP method and URI

POST /api/console/mfa-server-definitions

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 MFA Server Definition's name property.
description String Optional The value to be set as the MFA Server Definition's description property.
hostname-ipaddr String/ Hostname, String/ IPV4 Address, or String/ IPV6 Address Required The value to be set as the MFA Server Definition's hostname-ipaddr property.
port Integer Optional The value to be set as the MFA Server Definition's port property.

Response body contents

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

Field name Type Description
element-uri String/ URI Canonical URI path of the new MFA Server Definition object.

Description

This operation creates a new MFA Server Definition object.

On successful execution of this operation the MFA Server Definition is created using the values specified in the request body. The URI of the new MFA Server Definition is provided in the response body and in a Location response header.

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 the specified name is not unique. In addition, the API user must have action/task permission to the Manage Multi-factor Authentiction task; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements

This operation has the following authorization requirement:
  • Action/task permission to the Manage Multi-factor Authentication task.

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 MFA Server Definition: 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 An MFA Server Definition with the name specified in the request body already exists.
403 (Forbidden) 1 The API user does not have the required permission for this operation.

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

Example HTTP interaction

Figure 1. Create MFA Server Definition: Request
POST /api/console/mfa-server-definitions HTTP/1.1
x-api-session: 1l0nki6fyqq4zuue0lxmlahx8tnchoihm2w27cin0blkwma5l6
content-type: application/json
content-length: 121
{
   "description":"Company primary IBM MFA server",
   "hostname-ipaddr":"mfa1.internal.example.com",
   "name":"MFA server 1"
}
Figure 2. Create MFA Server Definition: Response
201 Created
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 26 Aug 2019 23:06:50 GMT
content-type: application/json
content-length: 90
{
   "element-uri":"/api/console/mfa-server-definitions/3007226a-c856-11e9-9df4-fa163e8e8d46"
}