> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # Request User Challenge `POST /api/web/v2/authentication/users/authenticate/{authenticator}` Request User Challenge ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | authenticator | path | Yes | string | Enum values: 21 | ## Request Body Required. ### application/json Schema ```json { "required": [ "applicationId" ], "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 (Required if the call to userQuery returned an authenticated 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 }, "locale": { "type": "string", "description": "The locale of this user. If not set, the default account locale will be used.", "example": "en" }, "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" }, "offlineTVS": { "type": "boolean", "description": "A flag indicating if the offline QR code token verification is used ", "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 }, "otpDeliveryAttribute": { "type": "string", "description": "OTP delivery attribute name.", "example": "Alternative Email" }, "otpDeliveryType": { "type": "string", "description": "Defines how a user receives their one-time passcode (Email, Text message (SMS), or Voice message (VOICE))", "example": "EMAIL/SMS/VOICE", "enum": [ "EMAIL", "SMS", "VOICE", "WECHAT", "WHATSAPP" ] }, "passthroughAuthenticatorParms": { "type": "object", "properties": { "passthroughAuthenticatorPlaceholders": { "type": "array", "description": "The list of placeholders.", "items": { "required": [ "name", "value" ], "type": "object", "properties": { "name": { "type": "string", "description": "The placeholder name." }, "value": { "type": "string", "description": "The placeholder value." } }, "description": "Passthrough authenticator placeholder", "title": "PassthroughAuthenticatorPlaceholder" } } }, "description": "Passthrough authenticator parameters", "title": "PassthroughAuthenticatorParms" }, "priority": { "type": "integer", "description": "The priority for push transactions where queuing is enabled. Default is 0 and allowed values are 0-9", "format": "int32" }, "pushMessageIdentifier": { "type": "string", "description": "Defines an identifier to retrieve customized SDK push message configuration", "example": "generic" }, "pushMutualChallengeEnabled": { "type": "boolean", "description": "A flag indicating if push mutual authentication is supported for tokens or Face Biometric", "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" }, "rpId": { "type": "string", "description": "Specifies the domain name (relying party ID) of your application and the passkey is registered with. Provide the domain only (e.g., example.com), without protocol (https://). Required if using a custom domain different from your IDaaS tenant’s hostname.", "example": "mycompany.example.com" }, "secondFactorAuthenticator": { "type": "string", "description": "Authenticator type selected for second factor (if enabled).", "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" ] }, "summary": { "type": "string", "description": "The push authentication challenge that appears in the user's mobile application.", "example": "You have requested to authenticate for a SAML Service Provider." }, "tokenPushMutualChallengeEnabled": { "type": "boolean", "description": "A flag indicating if the token push mutual authentication is supported", "example": true, "deprecated": true }, "transactionDetails": { "type": "array", "description": "Defines transaction details to be included in the challenge", "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. The userid is required for non-passwordless authenticators.", "example": "admin" } }, "description": "Request parameters for obtaining a challenge.", "title": "UserChallengeParameters" } ``` ## Responses ### 200 Authenticators retrieved successfully #### application/json Schema ```json { "type": "object", "properties": { "authenticationCompleted": { "type": "boolean", "description": "Flag to indicate if authentication has successfully completed." }, "authenticatorResponse": { "type": "string", "description": "The authenticator response for MSCHAPv2", "format": "byte" }, "deviceCertAuthDesired": { "type": "boolean", "description": "Flag to indicate if the user has to attempt device certificate authentication." }, "expires": { "type": "integer", "description": "Expiry time of token.", "format": "int64" }, "faceChallenge": { "type": "object", "properties": { "device": { "type": "string", "description": "Which device to use for registration and authentication.", "enum": [ "WEB", "MOBILE" ] }, "id": { "type": "string", "description": "The ID of the Face Biometric to get." }, "qrCode": { "type": "string", "description": "QR Code to use to launch the mobile flow." }, "sdkToken": { "type": "string", "description": "The SDK token generated for the user." }, "workflowRunId": { "type": "string", "description": "Workflow run ID to use for the user." } }, "description": "Parameters returned to initialize a Face Biometric authenticator.", "title": "FaceChallenge" }, "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" }, "firstName": { "type": "string", "description": "First Name." }, "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" }, "lastName": { "type": "string", "description": "Last Name." }, "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" }, "magicLinkType": { "type": "string", "description": "The type of Magic Link being used." }, "offlineTokenResponses": { "type": "object", "properties": { "firstMovingFactor": { "type": "integer", "description": "This is the moving factor index for the first hashed OTP returned. In the case of time-based tokens, it represents time step, otherwise it represents the value of the counter.", "format": "int64" }, "iterations": { "type": "integer", "description": "The number of iterations of the hash function to be performed.", "format": "int32" }, "maxSizeInUnits": { "type": "integer", "description": "This is the policy-configured maximum number (hours or counters)", "format": "int32" }, "maxTimeSteps": { "type": "integer", "description": "This is the max number of time steps used to validate a token.", "format": "int32" }, "minorSizeInUnits": { "type": "integer", "description": "This is the policy-configured recommended number (hours or counters)", "format": "int32" }, "otps": { "type": "string", "description": "An array of all of the OTPs returned in the batch, each with its public component of the salt." }, "privateSaltLength": { "type": "integer", "description": "The number of digits in the private part of the salt that the client must guess.", "format": "int32" }, "resultOptimized": { "type": "boolean", "description": "Flag indicating if the set of OTP hashes returned was optimized so that OTPs which have already been downloaded in prior requests, but that have no yet expired, are not sent again." }, "timeDrift": { "type": "integer", "description": "This is the token time drift in seconds. This applies only to time-based tokens.", "format": "int32" }, "timeInterval": { "type": "integer", "description": "If this contains a positive value then this batch is for time-based tokens, otherwise it is for event based tokens.", "format": "int32" }, "tokenSerialNumber": { "type": "string", "description": "The serial number of the token for which offline tokens are generated." }, "useSecret": { "type": "string", "description": "The secret the client should use when requesting the next batch of protected offline OTPs.", "format": "byte" } }, "description": "Used to return batches of protected OTPs for a given token", "title": "OfflineTokenAuthenticateResponse" }, "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" } }, "otpdeliveryType": { "type": "string", "description": "The OTP delivery type used.", "enum": [ "EMAIL", "SMS", "VOICE", "WECHAT", "WHATSAPP" ] }, "passthroughAuthenticationResponse": { "type": "object", "properties": { "passthroughAuthenticationResultItems": { "type": "array", "description": "Passthrough authentication result items.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the result item." }, "value": { "type": "string", "description": "The value of the result item." } }, "description": "Passthrough authentication result items.", "title": "PassthroughAuthenticationResultItems" } } }, "description": "Passthrough authenticator response.", "title": "PassthroughAuthenticationResponse" }, "passwordChallenge": { "type": "object", "properties": { "name": { "type": "string" }, "namedPasswordId": { "type": "string" } }, "title": "PasswordChallenge" }, "pushMutualChallenge": { "type": "string", "description": "Push authentication mutual challenge." }, "redirectUrl": { "type": "string", "description": "The redirect URL when using a Magic Link." }, "smartLoginChallenge": { "type": "string", "description": "For a SMART_LOGIN authenticator challenge, provides the challenge." }, "status": { "type": "string", "description": "Status of authenticator. This is not a required API field if Mobile Smart Credential or Token Push authentication is being used.", "enum": [ "CONFIRM", "CONCERN", "CANCEL", "NO_RESPONSE" ] }, "stepUpAuthExpiry": { "type": "integer", "description": "The timeout for step-up authentication", "format": "int64" }, "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", "description": "Authenticated/unauthenticated authorization token." }, "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 }, "transactionReceipt": { "type": "object", "properties": { "authenticationType": { "type": "string", "description": "The transaction authentication type.", "example": "OTP", "enum": [ "OTP", "TOKEN" ] }, "date": { "type": "string", "description": "The transaction date.", "format": "date-time", "example": "2020-02-01T12:13:24Z" }, "details": { "type": "array", "description": "The 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" } }, "id": { "type": "string", "description": "The transaction id.", "example": "Qwpfsc6AmWU6GHkvRzIhew==" }, "securityLevel": { "type": "string", "description": "The transaction authentication security level.", "example": "MEDIUM", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "userid": { "type": "string", "description": "The transaction user.", "example": "user1" } }, "description": "Transaction Receipt item and its value used with push authenticators and with offline transaction verification.", "title": "TransactionReceipt" }, "userCertificateChallenge": { "required": [ "challenge" ], "type": "object", "properties": { "challenge": { "type": "string" } }, "description": "For a user certificate authenticator challenge, provides the challenge.", "title": "UserCertificateChallenge" }, "userId": { "type": "string", "description": "The User ID of the Identity as a Service user that completed authentication." }, "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" }, "userRegistrationRequired": { "type": "boolean", "description": "Whether the user still requires registration." }, "userVerificationRequired": { "type": "boolean", "description": "Whether the user still requires verification." } }, "description": "Response associated with an authentication request.", "title": "AuthenticatedResponse" } ``` ### 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" } ```