> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # Risk-based authentication Use these examples to send the inputs used by Authentication API resource rules, including the client IP address, machine authentication data, transaction details, and requested Authentication Context Reference (ACR) values. ## Prerequisites Before you use these examples, configure the following: - An Authentication API application with **Source of Client IP Address for Resource Rule Risk Factors and Audits** set to **Provided in the API**. For other integration patterns, see [Choose the client IP address source](/docs/applications-and-sso/manage-applications/integrate-api-applications/integrate-authentication-api.md#choose-the-client-ip-address-source). - A resource rule that includes the required risk factors, such as Geolocation, Location History, Travel Velocity, Machine Authentication, Transaction, or External. See the [Authentication API resource rule example](/docs/applications-and-sso/manage-applications/integrate-api-applications/integrate-authentication-api.md#step-2-configure-a-resource-rule). - Risk-based authentication settings for location history and travel velocity. See [Modify risk-based authenticator general settings](/docs/authentication-and-security/manage-authenticators/manage-risk-based-authenticator-settings/modify-risk-based-authenticator-settings.md). - For Machine Authentication, a registered machine and its current nonce values. If a device fingerprint is required, collect it with the Entrust Device Fingerprint SDK. The end-to-end flow below sends the client IP address, machine data, the `knowledge` ACR, and RBA transaction details in each request. Remove `requestAcrs` or `transactionDetails` when the resource rule does not use those inputs. The example assumes that the resource rule maps low risk to password authentication and elevated risk to password plus a second factor. Your response values depend on your resource rule, authentication flows, user authenticators, and RBA history. ## Use inputs evaluated by IDaaS Date and Time does not require a request field. IDaaS evaluates its current time in the time zone configured in the risk factor. A Group access filter also does not require a request field because IDaaS uses the identified user's group memberships. For example, this request contains all the data required when a matching resource rule uses only the Date and Time risk factor and a Group access filter: ```json { "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27", "userId": "jsmith" } ``` ## Add an ACR access filter input When a resource rule uses an ACR access filter, send its configured ACR value in `requestAcrs`. For example, this request can select a rule configured for the `knowledge` ACR: ```json { "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27", "userId": "jsmith", "requestAcrs": "knowledge" } ``` Separate multiple requested ACR values with spaces. Include the same `requestAcrs` value in the user query, challenge, and challenge completion requests. ## Add Transaction and External risk inputs When a resource rule uses a Transaction risk factor, send the details referenced by its transaction rules in `transactionDetails`. An external risk engine can also consume these details, in addition to IDaaS account and user data and the client IP address. For example: ```json { "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27", "userId": "jsmith", "clientIp": "", "transactionDetails": [ { "detail": "Amount", "value": "10001", "usage": ["RBA"] }, { "detail": "Purpose", "value": "Transfer", "usage": ["RBA"] } ] } ``` The detail names must match the configured transaction rules or external risk engine requirements. Include the same RBA transaction details in the user query, challenge, and challenge completion requests. An External risk factor is separate from the `EXTERNAL` authenticator. ## Query the user's authenticators Send the end user's IP address, current machine data, requested ACR, and RBA transaction details when you query the user's authenticators: ```http POST https://customer.region.trustedauth.com/api/web/v2/authentication/users Content-Type: application/json ``` ```json { "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27", "userId": "jsmith", "clientIp": "", "machineAuthenticator": { "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==", "sequenceNonce": "ns2xIgb40uXJnxZYQ6DAqA==", "fingerprint": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}" }, "requestAcrs": "knowledge", "transactionDetails": [ { "detail": "Amount", "value": "10001", "usage": ["RBA"] }, { "detail": "Purpose", "value": "Transfer", "usage": ["RBA"] } ] } ``` Replace `` with the end user's public IPv4 address so IDaaS can resolve its location. Omit `fingerprint` when the tenant does not require device fingerprinting. For a recognized machine and location, the response can identify an authenticator allowed by the low-risk authentication flow. It can also return an updated sequence nonce. The following example shows only the response fields relevant to this flow: ```json { "authenticationTypes": ["PASSWORD"], "availableSecondFactor": null, "userMachineSettings": { "machineAuthenticatorEnabled": true, "deviceFingerprintRequired": true, "attributeExclusions": [] }, "machineAuthenticator": { "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==", "sequenceNonce": "Qn3zK8mY2pL5vR7sT9wX1A==", "fingerprint": null } } ``` Replace the stored nonce values with all nonce values returned in `machineAuthenticator` before making the next request. If the request has elevated risk, the response can instead contain an authentication type such as `PASSWORD_AND_SECONDFACTOR`. The response does not include the calculated risk level. If the matching resource rule also requires the Device Certificate context, the response contains `deviceCertAuthDesired: true`: ```json { "authenticationTypes": ["PASSWORD"], "deviceCertAuthDesired": true } ``` This field instructs the application to continue its supported Device Verification integration. It is not satisfied by `machineAuthenticator`. See [Device Verification outcomes](/api/auth-api/core-concepts/risk-based-authentication-and-machine-authentication.md#device-verification-outcomes). ## Request an authentication challenge Select an authenticator returned by the previous request. Include the same client IP address, requested ACR, transaction details, and the latest machine nonce values: ```http POST https://customer.region.trustedauth.com/api/web/v2/authentication/users/authenticate/PASSWORD Content-Type: application/json ``` ```json { "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27", "userId": "jsmith", "clientIp": "", "machineAuthenticator": { "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==", "sequenceNonce": "Qn3zK8mY2pL5vR7sT9wX1A==", "fingerprint": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}" }, "requestAcrs": "knowledge", "transactionDetails": [ { "detail": "Amount", "value": "10001", "usage": ["RBA"] }, { "detail": "Purpose", "value": "Transfer", "usage": ["RBA"] } ] } ``` The response contains a token for the challenge. It can also contain updated nonce values. The following partial response shows the machine data only: ```json { "machineAuthenticator": { "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==", "sequenceNonce": "aB4dE7gH0jK3mN6qR9tV2w==", "fingerprint": null } } ``` Replace the stored nonce values with the returned values before completing the challenge. ## Complete the authentication challenge Send the challenge response with the same client IP address, requested ACR, transaction details, and the latest machine data. Use the token returned by the challenge request in the `Authorization` header: ```http POST https://customer.region.trustedauth.com/api/web/v1/authentication/users/authenticate/PASSWORD/complete Authorization: Bearer Content-Type: application/json ``` ```json { "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27", "response": "user-password", "clientIp": "", "machineAuthenticator": { "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==", "sequenceNonce": "aB4dE7gH0jK3mN6qR9tV2w==", "fingerprint": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}" }, "requestAcrs": "knowledge", "transactionDetails": [ { "detail": "Amount", "value": "10001", "usage": ["RBA"] }, { "detail": "Purpose", "value": "Transfer", "usage": ["RBA"] } ] } ``` When authentication succeeds, the response sets `authenticationCompleted` to `true`. Store any returned machine and sequence nonces for the next authentication flow. ## Register a new machine If the user is registering the current machine, include `machineAuthenticatorRegistration` when completing a successful authentication challenge: ```json { "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27", "response": "user-password", "clientIp": "", "machineAuthenticatorRegistration": { "label": "Work laptop", "fingerprint": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}" }, "requestAcrs": "knowledge", "transactionDetails": [ { "detail": "Amount", "value": "10001", "usage": ["RBA"] }, { "detail": "Purpose", "value": "Transfer", "usage": ["RBA"] } ] } ``` The user must complete the minimum authentication level configured for machine registration. After successful registration, IDaaS returns `machineAuthenticator` with the nonce values to store. Omit `fingerprint` only when device fingerprinting is not required. ## Verify the risk evaluation The Authentication API response shows the authentication flow outcome, not the underlying risk calculation. Verify the expected behavior as follows: 1. Review `authenticationTypes` as an indication of the resulting authentication flow. The value also depends on the authenticators available to the user. 2. Complete the returned authentication flow and confirm that `authenticationCompleted` is `true`. 3. Use the authentication audit as the authoritative record of the selected resource rule, risk level, generated risk points, authentication flow, and individual risk factor results. See [View and export audit logs](/docs/reports-and-audits/view-and-export-audit-logs.md#risk-based-authentication-audit-details).