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

# Two-factor authentication

Use this raw HTTP example to complete password authentication followed by an OTP second factor. Before starting, configure an Authentication API application, assign it a resource rule that requires this flow, and assign the selected authenticators to the user.

The flow has five requests:

1. Query the user's authenticators.
2. Request the first-factor challenge.
3. Complete the first factor.
4. Request the second-factor challenge.
5. Complete the second factor.

## Query the user's authenticators

- **Method:** `POST`
- **Path:** `/api/web/v2/authentication/users`
- **Content type:** `application/json`

```json
{
  "userId": "jsmith",
  "applicationId": "11111111-1111-1111-1111-111111111111"
}
```

The response identifies the combined flow and the available second factors:

```json
{
  "authenticationTypes": ["PASSWORD_AND_SECONDFACTOR"],
  "availableSecondFactor": ["TOKENPUSH", "TOKEN", "OTP"]
}
```

## Request the first-factor challenge

- **Method:** `POST`
- **Path:** `/api/web/v2/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR`
- **Content type:** `application/json`

```json
{
  "userId": "jsmith",
  "applicationId": "11111111-1111-1111-1111-111111111111"
}
```

Store the returned challenge token:

```json
{
  "authenticationCompleted": false,
  "token": "<first-factor-challenge-token>"
}
```

## Complete the first factor

- **Method:** `POST`
- **Path:** `/api/web/v1/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR/complete`
- **Authorization:** `Bearer <first-factor-challenge-token>`
- **Content type:** `application/json`

```json
{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "response": "<user-password>"
}
```

The first factor does not complete the overall flow. Store the new token returned for the second-factor selection:

```json
{
  "authenticationCompleted": false,
  "token": "<first-factor-token>"
}
```

## Request the second-factor challenge

- **Method:** `POST`
- **Path:** `/api/web/v2/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR`
- **Content type:** `application/json`

```json
{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "secondFactorAuthenticator": "OTP",
  "authToken": "<first-factor-token>"
}
```

IDaaS sends the OTP and returns another challenge token:

```json
{
  "authenticationCompleted": false,
  "token": "<second-factor-challenge-token>",
  "otpdeliveryType": "SMS"
}
```

## Complete the second factor

- **Method:** `POST`
- **Path:** `/api/web/v1/authentication/users/authenticate/PASSWORD_AND_SECONDFACTOR/complete`
- **Authorization:** `Bearer <second-factor-challenge-token>`
- **Content type:** `application/json`

```json
{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "response": "123456",
  "secondFactorAuthenticator": "OTP"
}
```

When both factors succeed, the response contains the IDaaS authentication JWT:

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "token": "<idaas-jwt>"
}
```