Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Panel
borderColor#444544
titleColorwhite
borderWidth1
titleBGColor#444544
titlePrerequisites

1. Complete the steps in the Authentication API guide.

2. Configure the realm to enable Multi-Factor Authentication Methods.

Panel
borderColor#145570
titleColorwhite
borderWidth1
titleBGColor#145570
titleEndpoint

The /users/{username}/factors endpoint uses the GET method to access the end-user's profile and respond with the list of available Multi-Factor Authentication mechanisms

As a GET endpoint, there is no body, so no JSON parameters are required

Panel
borderColor#126591
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#126591
borderStylesolid
titleGET
HTTP MethodURIExample
GET

/api/v2/users/{username}/factors

https://secureauth.company.com/secureauth2/api/v2/users/jsmith/factors
UI Expand
titleDefinitions
  • status: The status of user ID provided (found, not_found, invalid, etc.); will always be in response
  • message: Additional information regarding the status; will always be in response
  • user_id: The user ID provided; will always be in response, whether successful or not
  • factors: The list of available multi-factor authentication methods available to the user
    • type: The type of method (phone, kbq, push, etc.)
    • id:The SecureAuth IdP Profile Property that is mapped to the directory field containing the information required to conduct the authentication (Phone1, Email2, etc.)
      • The indexed knowledge-based questions within the Knowledge-based Questions SecureAuth IdP Property (KBQ1, KBQ2, etc.)
      • A unique identifier provided to SecureAuth IdP by the mobile device during the provisioning process (for OATH and Push)
  • value: The information contained in the SecureAuth IdP Property / directory field (phone number, email address, device name, etc.)
  • capabilities: The variations available for the factor that require user selection (phone call, text message, etc.)  
UI Expand
titleGET Endpoint Response Examples
SuccessFail / Error
{
  "status": "found",
  "message": "",
  "user_id": "jsmith",
  "factors": [
    {
      "type": "phone",
      "id": "Phone1",
      "value": "123-456-7890",
      "capabilities": [
        "call"
      ]
    },
    {
      "type": "phone",
      "id": "Phone2",
      "value": "987-654-3210",
      "capabilities": [
        "sms",
        "call"
      ]
    },
    {
      "type": "email",
      "id": "Email1",
      "value": "jsmith@company.com"
    },
    {
      "type": "kbq",
      "id": "KBQ1",
      "value": "What city were you born in?"
    },
    {
      "type": "kbq",
      "id": "KBQ2",
      "value": "What was your favorite childhood game?"
    },
    {
      "type": "kbq",
      "id": "KBQ3",
      "value": "What was your dream job as a child?"
    },
    {
      "type": "kbq",
      "id": "KBQ4",
      "value": "Who is your personal hero?"
    },
    {
      "type": "kbq",
      "id": "KBQ5",
      "value": "What is the last name of your favorite school teacher?"
    },
    {
      "type": "kbq",
      "id": "KBQ6",
      "value": "What is the name of your favorite childhood pet?"
    },
    {
      "type": "help_desk",
      "id": "HelpDesk1",
      "value": "987-654-3210"
    },
    {
      "type": "help_desk",
      "id": "HelpDesk2",
      "value": "987-654-3211"
    },
    {
"type": "push",
"id": "8117b62897734d71b48ecdcab19bd437",
"value": "HTC One",
"biometricTypes": [
"fingerprint",
"face"
],
"capabilities": [
"push",
"push_accept",
"push_accept_symbol",
"push_accept_biometric"
]
},
{
"type": "oath",
"id": "63c6b390cac04efb8d283828ed29c120",
"value": "SecureAuth OTP Mobile App"
},
{
"type": "pin",
"value": "Private PIN"
}
],
}
{
  "status": "not_found",
  "message": "User Id was not found"
}
HTTP Status 404
{
  "status": "invalid_group",
  "message": "User Id is not associated with a valid group."
}
HTTP Status 200
{
  "status": "disabled",
  "message": "Account is disabled."
}
HTTP Status 200
{
  "status": "lock_out",
  "message": "Account is locked out."
}
HTTP Status 200
{
  "status": "password_expired",
  "message": "Password is expired."
}
HTTP Status 200

See Server Error information below

Anchor
Error
Error

UI Text Box
typeinfo

If a server error is encountered, then the follow response is returned:

Code Block
languagetext
{
  "status": "server_error",
  "message": "<Exception message describing the issue.>",
}
HTTP Status 500

...