> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # Query User Authenticators `POST /api/web/v2/authentication/users` Query User Authenticators ## Request Body Required. ### application/json Schema ```json { "required": [ "applicationId", "userId" ], "type": "object", "properties": { "applicationId": { "type": "string", "description": "Unique identifier of the Identity as a Service Authentication API application", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "authRequestKey": { "type": "string", "description": "Unique identifier of the client authentication request in the OIDC application's JWT IDaaS grant type use case." }, "authToken": { "type": "string", "description": "Authentication token." }, "clientIp": { "type": "string", "description": "Provided client IP address." }, "ignoreIPAddressForRBA": { "type": "boolean", "description": "Setting defines if IP Address is ignored for RBA or not. Default value is false and will not ignore IP Address for RBA.", "example": false }, "machineAuthenticator": { "type": "object", "properties": { "fingerprint": { "type": "string", "description": "The device fingerprint if it's required during Machine authentication. It will always be null when returned from IDaaS as part of the response body.", "example": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}" }, "machineNonce": { "type": "string", "description": "machineNonce", "example": "07ZeToA3YfoATTxoU6h2x==" }, "sequenceNonce": { "type": "string", "description": "sequenceNonce", "example": "03ReToA37851tyVU8f3y==" } }, "description": "Machine authenticator required to complete authentication challenge", "title": "MachineAuthenticator" }, "maxAge": { "type": "integer", "description": "Maximum Authentication Age. If an authentication token is supplied, the maximum authentication age used to determine whether authentication is required or not is based on the current system time or a supplied request time.", "format": "int32" }, "offlineTVS": { "type": "boolean", "description": "A flag indicating if the offline QR code token verification is used. Used only if a challenge is required for authentication when returnDefaultChallenge is true.", "example": true }, "origin": { "type": "string", "description": "The origin of the client. This field is deprecated, use rpId instead.", "example": "https://mycompany.example.com:443", "deprecated": true }, "priority": { "type": "integer", "description": "The priority for push transactions where queuing is enabled. Default is 0 and allowed values are 0-9. Used only if a challenge is required for authentication when returnDefaultChallenge is true.", "format": "int32" }, "pushMessageIdentifier": { "type": "string", "description": "Defines an identifier to retrieve customized SDK push message configuration. Used only if a challenge is required for authentication when returnDefaultChallenge is true.", "example": "generic" }, "pushMutualChallengeEnabled": { "type": "boolean", "description": "A flag indicating if push mutual authentication is supported for tokens or Face Biometric. Used only if a challenge is required for authentication when returnDefaultChallenge is true.", "example": true }, "requestAcrs": { "type": "string", "description": "The request acrs." }, "requestDetail": { "type": "object", "properties": { "browser": { "type": "string", "description": "The browser associated with the request.", "example": "Chrome 67.0.3396.99" }, "os": { "type": "string", "description": "The OS associated with the request.", "example": "Windows 8.1" } }, "description": "Request detail items.", "title": "RequestDetail" }, "requestTime": { "type": "integer", "description": "The request start time in milliseconds. If an authentication token and a maximum authentication age are supplied, determining whether authentication is required or not is based on the current system time if this value is not provided.", "format": "int64" }, "response": { "type": "string", "description": "Password response used for combined user ID and password login." }, "returnDefaultChallenge": { "type": "boolean", "description": "Flag indicating whether the service should include in the response the default challenge.", "example": true }, "rpId": { "type": "string", "description": "The Relying Party ID associated with the passkey. This identifies the domain or origin for which the passkey is registered. This field is mandatory if domain is outside of the IDaaS hostname.", "example": "mycompany.example.com" }, "summary": { "type": "string", "description": "The push authentication challenge that appears in the user's mobile application. Used only if a challenge is required for authentication when returnDefaultChallenge is true.", "example": "You have requested to authenticate for a SAML Service Provider." }, "supportChoosingOtpDelivery": { "type": "boolean", "description": "Deprecated : Clients who support choosing OTP delivery can still work without having to supply this flag.Flag indicating whether client supports choosing OTP delivery contact attribute.If the client doesn't support it and default OTP delivery is set to NONE, OTP won't be available as an authenticator.", "example": true, "deprecated": true }, "tokenPushMutualChallengeEnabled": { "type": "boolean", "description": "A flag indicating if the token push mutual authentication is supported. Used only if a challenge is required for authentication when returnDefaultChallenge is true.", "example": true, "deprecated": true }, "transactionDetails": { "type": "array", "description": "Transaction Details.", "items": { "type": "object", "properties": { "detail": { "type": "string", "description": "The transaction detail name.", "example": "Amount" }, "usage": { "type": "array", "items": { "type": "string", "description": "The transaction detail usage. If not provided, the attribute supports all usages. RBA indicates that the detail is used for risk-based authentication; TVS indicates that the detail is used for transaction verification.", "example": "RBA", "enum": [ "RBA", "TVS" ] } }, "value": { "type": "string", "description": "The transaction detail value.", "example": "$10,001" } }, "description": "Transaction detail item and its value used with push authenticators and with offline transaction verification.", "title": "TransactionDetail" } }, "userId": { "type": "string", "description": "User ID (containing the user ID or a user alias) of the Identity as a Service user completing the authentication challenge.", "example": "user" } }, "description": "Request parameters for starting user authentication process.", "title": "UserAuthenticateQueryParameters" } ``` ## Responses ### 200 Authenticators retrieved successfully #### application/json Schema ```json { "type": "object", "properties": { "authenticationCompleted": { "type": "boolean", "description": "Flag to indicate if access to the application is allowed with the current JWT." }, "authenticationTypes": { "type": "array", "description": "List of authenticator types available for the user.", "items": { "type": "string", "description": "List of authenticator types available for the user.", "enum": [ "MACHINE", "PASSWORD", "EXTERNAL", "KBA", "TEMP_ACCESS_CODE", "OTP", "GRID", "TOKEN", "TOKENCR", "TOKENPUSH", "FIDO", "SMARTCREDENTIALPUSH", "PASSWORD_AND_SECONDFACTOR", "SMART_LOGIN", "IDP", "PASSKEY", "IDP_AND_SECONDFACTOR", "USER_CERTIFICATE", "FACE", "PASSTHROUGH", "MAGICLINK" ] } }, "authenticatorLockoutStatus": { "type": "array", "description": "A list of all authenticators that the user has with their lockout status.", "items": { "type": "object", "properties": { "locked": { "type": "boolean", "description": "Determines if this authenticator is currently locked out." }, "lockoutDate": { "type": "string", "description": "The date the user was locked. Null means the user is not locked.", "format": "date-time", "example": "2019-02-19T13:15:27Z" }, "lockoutExpiryDate": { "type": "string", "description": "if remainingAuthenticationAttempts is 0 then a lockoutExpiryDate of null means the lockout never expires. Otherwise a value of null means the user isn't locked out.", "format": "date-time", "example": "2019-02-20T13:15:27Z" }, "name": { "type": "string", "description": "The users named password authentication that is locked out." }, "remainingAuthenticationAttempts": { "type": "integer", "description": "The number of authentication attempts remaining before the user is locked out.", "format": "int32" }, "type": { "type": "string", "description": "The type of the authenticator.", "example": "OTP", "enum": [ "MACHINE", "PASSWORD", "EXTERNAL", "KBA", "TEMP_ACCESS_CODE", "OTP", "GRID", "TOKEN", "TOKENCR", "TOKENPUSH", "FIDO", "SMARTCREDENTIALPUSH", "PASSWORD_AND_SECONDFACTOR", "SMART_LOGIN", "IDP", "PASSKEY", "IDP_AND_SECONDFACTOR", "USER_CERTIFICATE", "FACE", "PASSTHROUGH", "MAGICLINK" ] } }, "description": "Detailed lockout information for each authenticator for a particular user.", "title": "UserAuthenticatorLockoutStatus" } }, "availableSecondFactor": { "type": "array", "description": "Lists authenticator types available to complete second factor challenge (if enabled).", "items": { "type": "string", "description": "Lists authenticator types available to complete second factor challenge (if enabled).", "enum": [ "MACHINE", "PASSWORD", "EXTERNAL", "KBA", "TEMP_ACCESS_CODE", "OTP", "GRID", "TOKEN", "TOKENCR", "TOKENPUSH", "FIDO", "SMARTCREDENTIALPUSH", "PASSWORD_AND_SECONDFACTOR", "SMART_LOGIN", "IDP", "PASSKEY", "IDP_AND_SECONDFACTOR", "USER_CERTIFICATE", "FACE", "PASSTHROUGH", "MAGICLINK" ] } }, "deviceCertAuthDesired": { "type": "boolean", "description": "Flag to indicate if the user has to attempt device certificate authentication." }, "expires": { "type": "integer", "format": "int64" }, "fidoChallenge": { "required": [ "challenge", "timeout", "timeoutMillis" ], "type": "object", "properties": { "allowCredentials": { "type": "array", "description": "The list of IDs of the FIDO tokens registered for the user. Each value is base-64 encoded.", "items": { "type": "string", "description": "The list of IDs of the FIDO tokens registered for the user. Each value is base-64 encoded." } }, "challenge": { "type": "string", "description": "A random challenge. It is a base-64 encoded value." }, "timeout": { "type": "integer", "description": "The number of seconds that the client will wait for the FIDO token to respond. This field is deprecated, use 'timeoutMillis' instead.", "format": "int32", "deprecated": true }, "timeoutMillis": { "type": "integer", "description": "The number of milliseconds that the client will wait for the FIDO token to respond.", "format": "int32" } }, "description": "If the authentication challenge is of type FIDO, the FIDOChallenge will contain the FIDO challenge parameters that must be passed to the FIDO token to complete authentication.", "title": "FIDOChallenge" }, "gridChallenge": { "required": [ "cellAlphabets", "challenge", "gridInfo", "numCharsPerCell" ], "type": "object", "properties": { "cellAlphabets": { "type": "string", "description": "The cellAlphabets value specifies the characters that are valid for the cells in the grid challenge." }, "challenge": { "type": "array", "description": "The grid challenge specifies a list of grid cells that the user must answer in their challenge.", "items": { "required": [ "column", "row" ], "type": "object", "properties": { "column": { "type": "integer", "description": "The column within the grid starting at 0.", "format": "int32" }, "row": { "type": "integer", "description": "The row within the grid starting at 0.", "format": "int32" } }, "description": "A GridChallengeCell specifies one cell in a grid by its row and column coordinates. Normally a grid challenge cell is displayed using letters for the column and numbers for the row. For example, a cell with the value 0,0 will be displayed as A1.", "title": "GridChallengeCell" } }, "gridInfo": { "type": "array", "description": "The grid details.", "items": { "required": [ "serialNumber" ], "type": "object", "properties": { "expiryDate": { "type": "string", "description": "The expiry date of the grid. Null value indicates the grid will never expire.", "format": "date-time", "example": "2019-02-19T13:15:27Z" }, "serialNumber": { "type": "string", "description": "The serial number of the grid that can be used to answer this challenge." } }, "description": "Details about the grid.", "title": "GridInfo" } }, "numCharsPerCell": { "type": "integer", "description": "The numCharsPerCell value specifies the number of characters expected in the response for each cell as defined by current settings.", "format": "int32" } }, "description": "If the authentication challenge is of type grid, the GridChallenge object will contain the grid challenge that the end user must answer.", "title": "GridChallenge" }, "kbaChallenge": { "required": [ "userQuestions" ], "type": "object", "properties": { "id": { "type": "string" }, "userQuestions": { "type": "array", "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The question's answer." }, "id": { "type": "string", "description": "The UUID of the KBA question/answer." }, "question": { "type": "string", "description": "The question." } }, "description": "A KBA question/answer stored for a user.", "title": "UserQuestion" } } }, "description": "Knowledge-based authenticator required for authentication to Identity as a Service", "title": "KbaChallenge" }, "machineAuthenticator": { "type": "object", "properties": { "fingerprint": { "type": "string", "description": "The device fingerprint if it's required during Machine authentication. It will always be null when returned from IDaaS as part of the response body.", "example": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}" }, "machineNonce": { "type": "string", "description": "machineNonce", "example": "07ZeToA3YfoATTxoU6h2x==" }, "sequenceNonce": { "type": "string", "description": "sequenceNonce", "example": "03ReToA37851tyVU8f3y==" } }, "description": "Machine authenticator required to complete authentication challenge", "title": "MachineAuthenticator" }, "organizations": { "type": "array", "description": "A list of the user organizations.", "items": { "required": [ "displayName", "id", "name" ], "type": "object", "properties": { "description": { "type": "string", "description": "The description of the organization." }, "displayName": { "type": "string", "description": "The display name of the organization." }, "id": { "type": "string", "description": "The unique UUID assigned to the organization when it is created." }, "logoUri": { "type": "string", "description": "The URI of the logo to display when showing organizations.", "example": "https://account.mycompany.com/images/logo.png" }, "name": { "type": "string", "description": "The name of the organization." } }, "description": "Organization defines the attributes of an organization used in B2B scenarios.", "title": "Organization" } }, "otpDeliveryInfo": { "type": "object", "properties": { "availableOTPDelivery": { "type": "array", "description": "The available delivery types.", "items": { "type": "string", "description": "The available delivery types.", "enum": [ "EMAIL", "SMS", "VOICE", "WECHAT", "WHATSAPP" ] } }, "otpContactValues": { "type": "array", "description": "The available OTP contact values types.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the attribute.", "example": "alternativeEmail" }, "type": { "type": "string", "description": "Type of the OTP delivery attribute.", "example": "EMAIL", "enum": [ "EMAIL", "SMS", "VOICE", "WECHAT", "WHATSAPP" ] }, "value": { "type": "string", "description": "Masked attribute value.", "example": "*******@mycompany.com" } }, "description": "OTPContactValue", "title": "OTPContactValue" } }, "otpDefaultDelivery": { "type": "string", "description": "The default delivery type.", "enum": [ "EMAIL", "SMS", "VOICE", "WECHAT", "WHATSAPP" ] }, "otpDeliveryAttribute": { "type": "string", "description": "The name of default OTP delivery attribute.", "example": "Alternative Email" } }, "description": "OTPDetails", "title": "OTPDetails" }, "otpDeliveryType": { "type": "string", "description": "The OTP delivery type used.", "enum": [ "EMAIL", "SMS", "VOICE", "WECHAT", "WHATSAPP" ] }, "passwordChallenge": { "type": "object", "properties": { "name": { "type": "string" }, "namedPasswordId": { "type": "string" } }, "title": "PasswordChallenge" }, "passwordResetAllowed": { "type": "boolean", "description": "Flag to indicate if the user can initiate a password reset flow." }, "pushMutualChallenge": { "type": "string", "description": "Push authentication mutual challenge for token or Face Biometric." }, "registrationRequired": { "type": "boolean", "description": "Flag to indicate if the user has to register authenticators." }, "supportsSignature": { "type": "boolean", "description": "Flag to indicate if the user has a token that supports signature." }, "tempAccessCodeChallenge": { "type": "object", "properties": { "adminContact": { "type": "string", "description": "An optional admin contact value (like an admin email address or phone number) to be displayed in the admin contact message." }, "enableAdminContact": { "type": "boolean", "description": "Indicates if the admin contact message should be displayed for this challenge." } }, "description": "Information about the temporary access code settings.", "title": "TempAccessCodeChallenge" }, "time": { "type": "integer", "format": "int64" }, "token": { "type": "string" }, "tokenChallenge": { "required": [ "token" ], "type": "object", "properties": { "challenge": { "type": "string", "description": "For TOKENCR authentication, the challenge that must be entered into the token. Will be null for TOKEN and TOKENPUSH authentication." }, "token": { "type": "array", "description": "The token challenge contains a list of TokenInfo objects for each of the tokens that can be used to authenticate. In the case of an offline QR code challenge, a TokenInfo object includes the QR code.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Optional label to identify an assigned token: a String up to 100 characters.", "example": "PENDING" }, "qrCode": { "type": "string", "description": "The base-64 encoded QR code. This QR code can be scanned by the Entrust Identity mobile application to perform activation in the case of an offline QR code challenge." }, "qrCodeUrl": { "type": "string", "description": "The URL based QR code string. In the case of an offline QR code challenge, this string can be used to generated the base-64 encoded QR code." }, "serialNumber": { "type": "string", "description": "The serial number of the token." } }, "description": "A TokenInfo specifies one token that can be used to authenticate with a token serial number, a base-64 QR code string and a url based QR code string.", "title": "TokenInfo" } } }, "description": "If the authentication challenge is of offline token, the TokenChallenge object will contain the QR codes can be scanned by the mobile app.", "title": "TokenChallenge" }, "tokenDetails": { "type": "array", "description": "For a token or token push authenticator challenge, provides a list of serial numbers of the tokens that can be used to authenticate.", "items": { "type": "string", "description": "For a token or token push authenticator challenge, provides a list of serial numbers of the tokens that can be used to authenticate." } }, "tokenPushMutualChallenge": { "type": "string", "description": "The token push authentication mutual challenge.", "deprecated": true }, "userMachineSettings": { "type": "object", "properties": { "attributeExclusions": { "type": "array", "description": "List of device fingerprinting attributes that should not be collected when a device fingerprint is captured.", "items": { "type": "string", "description": "List of device fingerprinting attributes that should not be collected when a device fingerprint is captured." } }, "deviceFingerprintRequired": { "type": "boolean", "description": "Indicates whether a device fingerprint should be captured during machine registration or authentication" }, "machineAuthenticatorEnabled": { "type": "boolean", "description": "machineAuthenticatorEnabled" }, "userMachineAuthenticators": { "type": "array", "description": "List of Machine Authenticators that the user currently has--used to prevent duplicated labels.", "items": { "required": [ "id", "label", "registrationTime" ], "type": "object", "properties": { "expiryTime": { "type": "string", "description": "When this machine secret expires in UTC time", "format": "date-time", "example": "2019-02-19T13:15:27Z" }, "id": { "type": "string", "description": "Identifies the device/machine" }, "label": { "type": "string", "description": "Identifies the device/machine from the end-user point of view" }, "lastUsedTime": { "type": "string", "description": "When this machine secret was last used", "format": "date-time", "example": "2019-02-19T13:15:27Z" }, "registrationTime": { "type": "string", "description": "When this machine secret was created in UTC time", "format": "date-time", "example": "2019-02-19T13:15:27Z" } }, "description": "UserMachineAuthenticator", "title": "UserMachineAuthenticator" } } }, "description": "UserMachineSettings", "title": "UserMachineSettings" }, "verificationRequired": { "type": "boolean", "description": "Flag to indicate if the user has to verify." } }, "description": "Response associated with user authentication query.", "title": "UserAuthenticateQueryResponse" } ``` ### 400 Bad request #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 401 Access denied #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 403 Forbidden #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 404 Not Found #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ```