List MFA Server Definitions

The List MFA Server Definitions operation lists MFA Server Definitions defined to the console.

HTTP method and URI

GET /api/console/mfa-server-definitions

Query Parameters

Name Type Rqd/Opt Description
name String Optional Filter pattern (regular expression) to limit returned objects to those that have a matching name property.

Response body contents

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

Field name Type Description
mfa-server-definitions Array of mfa-server-definition-info objects Array of nested mfa-server-definition-info objects as described in the next table.

Each nested mfa-server-definition-info object contains the following fields:

Field name Type Description
element-uri String/ URI The element-uri property of the MFA Server Definition object.
name String The name property of the MFA Server Definition object.

Description

This operation lists MFA Server Definitions defined to the console. Some basic properties are provided for each MFA Server Definition that is included in the response.

If the name query parameter is specified, the returned list is limited to those MFA Server Definitions that have a name property matching the specified filter pattern. If the name parameter is omitted, no such filtering is performed.

An MFA Server Definition is included in the list only if the API user has user-related-access permission to that object or action/task permission to the Manage Multi-factor Authentication task. If there is an MFA Server Definition to which the API user does not have permission, that object is omitted from the list, but no error status code results.

If there are no MFA Server Definitions defined to the console or if no MFA Server Definitions are to be included in the results due to filtering or access permissions, an empty list is provided and the operation completes successfully.

Authorization requirements

This operation has the following authorization requirement:
  • User-related-access permission to the MFA Server Definition objects included in the response body or action/task permission to the Manage Multi-factor Authentication task.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in Response body contents.

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.

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.
14 A query parameter contains an invalid value.

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

Example HTTP interaction

Figure 1. List MFA Server Definitions: Request
GET /api/console/mfa-server-definitions HTTP/1.1
x-api-session: 2q7icwfrl9deu0rxrupb0p6mobcvirs0w4y1bvtfocrz0ix5fl
Figure 2. List MFA Server Definitions: Response
200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 26 Aug 2019 23:13:32 GMT
content-type: application/json
content-length: 254
{
   "mfa-server-definitions":[
      {
         "element-uri":"/api/console/mfa-server-definitions/14ef02da-c857-11e9-8189-fa163e8e8d46",
         "name":"MFA server 2"
      },
      {
         "element-uri":"/api/console/mfa-server-definitions/3007226a-c856-11e9-9df4-fa163e8e8d46",
         "name":"MFA server 1"
      }
   ]
}