> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Integrate Authentication API

Add an Authentication API application to integrate your application with the IDaaS authentication APIs. After you configure the application, users enter IDaaS challenge responses in your application interface, and your application sends those responses to IDaaS to authenticate users and grant access.

See the [_Identity as a Service Authentication API Guide_](/api/auth-api/getting-started.md) for more information.

## Step 1: Add an Authentication API and configure the General settings

To create an Authentication API application, complete the following steps.

1. Go to Menu icon **>** **Security > Applications**. The **Applications** page appears.
2. Click **+**. The **Select an Application Template** page appears.
3. Do one of the following:
   - Select the **IDaaS Integrations** button and scroll to find the application you want to add to IDaaS.
   - In the **Search bar**, enter a search option to filter for the application you want to add to IDaaS.
4. Click **Authentication API**. The **Add Authentication API** page appears.
5. Configure the **App Settings**.
   1. In the **Application Name** field, type a name for your application.
   2. In the **Application Description** field, enter a description for your application.
   3. Copy and paste the **Application ID** into the IDaaS API calls being used by your application.
   4. Select the **Source of Client IP Address for Resource Rule Risk Factors and Audits**. The options are:
      - **Not provided.** The IP address is not provided and is not extracted from the connection.
      - **Provided in the API.** The IP address is provided in the request body of the API.
      - **From the incoming HTTP connection.** The IP address is extracted from the connection.
6. Click **Show Advanced Settings** to configure the advanced settings, and select the following optional settings:
   - **Use Client IP Address Only for Audits** to allow Authentication API requests to exclude the client IP address from resource rule risk factor evaluation while retaining it in authentication audits.
   - **Require User Verification** to require user verification through the Auth API for Identity Provider authentication.
   - **Manage Client Values** to allow the Auth API to call self-admin (internal) APIs that are used to manage client values.
7. Click **Save**.

### Choose the client IP address source

The client IP address source determines which address IDaaS uses for resource rule risk factors and authentication audits. The following table shows the typical source for each integration pattern.

| Integration pattern                    | Typical client IP address source      | Request requirement                                                                                                                                                                   |
| -------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Browser calls IDaaS directly           | **From the incoming HTTP connection** | Omit `clientIp`. IDaaS uses the source address of the connection.                                                                                                                     |
| Browser calls your backend, then IDaaS | **Provided in the API**               | Collect the end user's IPv4 address in your backend and include it as `clientIp` in each Authentication API request. IDaaS rejects a provided value that is not a valid IPv4 address. |
| No client IP address is available      | **Not provided**                      | Omit `clientIp`. Do not use this option when the resource rule contains IP-based risk factors. A missing IP address can cause those factors to fail and increase the evaluated risk.  |

The following diagram shows where the client IP address and machine data enter each request path and how IDaaS uses them:

100%

When you select **Provided in the API**, IDaaS uses the `clientIp` value from the request body. When you select **From the incoming HTTP connection**, a `clientIp` value in the request body does not replace the connection address.

Backend and proxy connections

If your backend or a proxy calls IDaaS, **From the incoming HTTP connection** can identify that intermediary instead of the end user. Select **Provided in the API** when IDaaS must evaluate the end user's address, and accept forwarded addresses only from trusted infrastructure.

Browser applications that call the Authentication API directly must also have an allowed Authentication API CORS origin. See [Manage Cross Origin Resource Sharing (CORS)](/docs/authentication-and-security/manage-cross-origin-resource-sharing-cors.md).

If you enable **Use Client IP Address Only for Audits**, include `ignoreIPAddressForRBA` with a value of `true` in each query, challenge, and challenge completion request where the IP address must be excluded from risk evaluation:

```json
{
  "clientIp": "203.0.113.10",
  "ignoreIPAddressForRBA": true
}
```

If you omit `ignoreIPAddressForRBA` or set it to `false`, IDaaS uses the client IP address for configured resource rule risk factors. IDaaS always retains the address in the authentication audit.

## Step 2: Configure a resource rule

1. Click the **Resource Rules** tab.

2. Click **Add Resource Rule**.

3. Configure the resource rule for your authentication policy. The following example uses location, machine, and transaction signals to require stronger authentication when IDaaS evaluates elevated risk.

   | Resource rule setting | Example configuration                                                                                                                                                              |
   | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | Name                  | `Authentication API RBA example`                                                                                                                                                   |
   | Group access filter   | Do not add this filter when the rule applies to all users. Add selected groups when the rule applies only to those users.                                                          |
   | ACR access filter     | Optional. Select the `knowledge` ACR when clients send `"requestAcrs": "knowledge"`. Omit this filter when ACR must not determine whether the rule applies.                        |
   | Risk factors          | Add Geolocation, Location History, Travel Velocity, Machine Authentication, and Transaction when your policy uses all the corresponding signals.                                   |
   | Risk weights          | Assign weights based on the relative importance of each configured factor. Use **Risk Simulation** to confirm that the combined results produce the intended risk level.           |
   | Low-risk outcome      | Select an authentication flow that requires password authentication.                                                                                                               |
   | Elevated-risk outcome | Select an authentication flow that requires password authentication and a second factor. Configure separate medium- and high-risk outcomes if your policy treats them differently. |

4. Configure each added risk factor:

   - For Geolocation, select the allowed or denied countries.
   - Location History uses the tenant's risk-based authenticator settings.
   - Travel Velocity uses the configured travel velocity threshold.
   - For Machine Authentication, configure the fingerprint mismatch risk limit.
   - For Transaction, select the transaction rules and configure the risk limit. The request detail names must match the transaction items used by these rules.
   - Optional. Add External when the rule uses a configured external risk engine.

5. Configure the risk weights, risk-level thresholds, and authentication flows for low, medium, and high risk.

6. Use **Risk Simulation** to verify representative combinations of passed and failed factors.

7. Save and enable the resource rule.

For complete configuration instructions, see [Create resource rules](/docs/authentication-and-security/create-and-manage-resource-rules/create-resource-rules.md). For requests that supply the inputs used by this example, see [Risk-based authentication](/api/auth-api/rest-examples/risk-based-authentication.md).