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

# Getting Started

IDaaS provides an Authentication API that lets you authenticate users programmatically with supported authenticators. Use this guide to create an Authentication API application, review the authentication flow, initialize a client, and make your first authentication request.

## Start here

Start with the resource that matches your task:

- Use the [Authentication API reference](/api/auth-api/reference.md) when you need endpoint details, request and response schemas, or interactive testing. Before sending test requests from the API Explorer, enter your IDaaS tenant URL and add this site's origin to your IDaaS CORS origins.
- Use [Client setup](/api/auth-api/sdk-examples/api-client-install.md) when you want to install a generated client for your preferred programming language.

## Download the OpenAPI file

Download the raw OpenAPI JSON file when you want to import the schema into Postman, generate a client, or validate requests locally.

### Authentication API OpenAPI file

Download the OpenAPI JSON file, or open it in a new tab for inspection.

[Download JSON](/openapi/authentication.json)[Open in new tab](/openapi/authentication.json)

## Prerequisites

Before you run the examples in this guide, make sure you have:

- An [Authentication API application](/docs/applications-and-sso/manage-applications/integrate-api-applications/integrate-authentication-api.md) in IDaaS.
- A [resource rule](/docs/authentication-and-security/create-and-manage-resource-rules/create-resource-rules.md) assigned to the Authentication API application.
- The application ID and IDaaS hostname from the [Authentication API application settings](/docs/applications-and-sso/manage-applications/integrate-api-applications/integrate-authentication-api.md).
- A test user who is registered in IDaaS and [assigned the authenticator](/docs/people-and-access/manage-members/add-users-to-identity-as-a-service/assign-user-authenticators.md) you want to test.

## Create an Authentication API application in IDaaS

1. Go to your IDaaS Admin portal and navigate to `Security > Applications`.
2. Click `+`, and then select **Authentication API** from the list of available applications.
3. In the **General** tab, enter the name and description of your application.
4. Click **Next**.
5. In the **Setup** tab, set the **Source of Client IP Address for Resource Rule Risk Factors and Audits**.
6. In the **Complete** tab, click **Copy** to copy the `applicationID` to your clipboard. You need the `applicationID` to initialize the Authentication API. Example: `9aaf0071-3f79-4663-9782-932c7d53c3da`.
7. Add a resource rule to your Authentication API application.

Required setup

A resource rule must be added to your Authentication API application.

## Authentication flow

IDaaS uses three API calls to complete an authentication challenge:

1. Get User's Authenticators.
2. Select Authenticator.
3. Complete Authentication Challenge.

Make these API calls sequentially. Each response contains information that is required to complete the next call.

## Select an available authenticator

Use an authenticator returned in `authenticationTypes` or `availableSecondFactor` by Get User's Authenticators. The
available values depend on the user's registered authenticators and the resource rule selected for the request. Do not
construct the value from a fixed list.

`MACHINE` is used internally for Machine Authentication risk evaluation. It cannot be selected for an Authentication API
challenge. Send machine data in `machineAuthenticator` instead.

## Initialize the Authentication API client

To call the API, initialize the Authentication API client using the `applicationID` you copied when you created the application.

**Java**

```java
import com.entrustdatacard.intellitrust.auth.ApiClient;
import com.entrustdatacard.intellitrust.auth.api.AuthenticationApi;
import com.entrustdatacard.intellitrust.auth.model.AuthenticatedResponse;
import com.entrustdatacard.intellitrust.auth.model.UserAuthenticateParameters;
import com.entrustdatacard.intellitrust.auth.model.UserChallengeParameters;

public class Main {
  private static final String APPLICATION_ID = "YOUR_APPLICATION_ID";
  private static final String HOST_NAME = "YOUR_HOST_NAME";

  public static void main(String args[]) throws Exception {
      // initialize the API client with the IDaaS hostname
      ApiClient apiClient = new ApiClient();
      apiClient.setBasePath(HOST_NAME);
  }
}
```

**CSharp**

```csharp
using com.entrustdatacard.intellitrust.auth.api;
using com.entrustdatacard.intellitrust.auth.Client;
using com.entrustdatacard.intellitrust.auth.model;

namespace Sample
{
    internal class AuthApiSample
    {
        private static readonly string HOST_NAME = "YOUR_HOST_NAME";
        private static readonly string APPLICATION_ID = "YOUR_APPLICATION_ID";

        public static void Main()
        {
            Configuration configuration = new Configuration();
            configuration.BasePath = HOST_NAME;

            var authApi = new AuthenticationApi(configuration);
        }
    }
}
```

**Python**

```python
from IntelliTrust_Python_Authentication import ApiClient, Configuration
import IntelliTrust_Python_Authentication.api as apis
import IntelliTrust_Python_Authentication.models as models
import IntelliTrust_Python_Authentication.exceptions as exceptions

conf = Configuration(host="YOUR_HOST_NAME")
with ApiClient(conf) as api_client:
    # create an instance of the authentication API
    auth_api = apis.AuthenticationApi(api_client)
```

## Try API requests

After you initialize the client, you can make calls to the Authentication API. The following example authenticates a user who is registered in IDaaS and assigned the selected authenticator.

**Java**

```java
String authType = args[0];
String userId = args[1];

UserChallengeParameters challengeParms = new UserChallengeParameters();
challengeParms.setApplicationId(APPLICATION_ID);
challengeParms.setUserId(userId);

AuthenticatedResponse challengeResponse = authApi.userChallengeUsingPOST(authType, challengeParms);

String response = System.console().readLine("Enter response: ");
UserAuthenticateParameters authParms = new UserAuthenticateParameters()
    .setApplicationId(APPLICATION_ID)
    .setResponse(response);
authApi.userAuthenticateUsingPOST(authType, authParms, challengeResponse.getToken());
```

**CSharp**

```csharp
String userId = null;
do
{
    Console.WriteLine("Enter the User ID of existing user.");
    userId = Console.ReadLine().Trim();
} while (userId == null || userId.Length == 0);

String authType = null;
do
{
    Console.WriteLine("Enter the authentication type (PASSWORD, OTP, KBA, etc.)");
    authType = Console.ReadLine().Trim();
} while (authType == null || authType.Length == 0);

Console.WriteLine("Authenticating user " + userId);
var challengeParams = new UserChallengeParameters(applicationId: APPLICATION_ID, userId: userId);
AuthenticatedResponse challengeResponse = authApi.UserChallengeUsingPOST(authType, challengeParams);

String response = Console.ReadLine().Trim();
var authParams = new UserAuthenticateParameters(applicationId: APPLICATION_ID, response: response);
authApi.UserAuthenticateUsingPOST(authType, authParams, challengeResponse.Token);
```

**Python**

```python
auth_type = input("Enter the authentication type (PASSWORD, OTP, KBA, etc.): ")
user_id = input("Enter the User ID of existing user: ")

user_challenge_parameters = models.UserChallengeParameters(application_id=APPLICATION_ID, user_id=user_id)
challenge_response = auth_api.user_challenge_using_post(auth_type, user_challenge_parameters)

response = input("Enter response: ")
user_authenticate_parameters = models.UserAuthenticateParameters(application_id=APPLICATION_ID, response=response)
try:
    auth_response = auth_api.user_authenticate_using_post(auth_type, user_authenticate_parameters, challenge_response.token)
    if auth_response.authentication_completed:
        print("Authentication successful")
except exceptions.ForbiddenException as e:
    print("Authentication failed: " + e.reason)
```

## Full example snippet

**Java**

```java
package com.entrust.idaas.userAuthenticate;

import com.entrustdatacard.intellitrust.auth.ApiClient;
import com.entrustdatacard.intellitrust.auth.api.AuthenticationApi;
import com.entrustdatacard.intellitrust.auth.model.*;

public class UserAuthenticate {
    private static final String APPLICATION_ID = "YOUR_APPLICATION_ID";
    private static final String HOST_NAME = "YOUR_HOST_NAME";

    public static void main(String args[]) throws Exception {
        ApiClient apiClient = new ApiClient();
        apiClient.setBasePath(HOST_NAME);
        AuthenticationApi authApi = new AuthenticationApi(apiClient);

        if (args.length != 2) {
            System.err.println("userAuthenticate <authType> <userId>");
            System.exit(-1);
        }
        String authType = args[0];
        String userId = args[1];

        UserChallengeParameters challengeParms = new UserChallengeParameters();
        challengeParms.setApplicationId(APPLICATION_ID);
        challengeParms.setUserId(userId);

        AuthenticatedResponse challengeResponse = authApi.userChallengeUsingPOST(authType, challengeParms);

        String response = System.console().readLine("Enter response: ");
        UserAuthenticateParameters authParms = new UserAuthenticateParameters()
            .setApplicationId(APPLICATION_ID)
            .setResponse(response);
        authApi.userAuthenticateUsingPOST(authType, authParms, challengeResponse.getToken());
    }
}
```

**CSharp**

```csharp
using com.entrustdatacard.intellitrust.auth.api;
using com.entrustdatacard.intellitrust.auth.Client;
using com.entrustdatacard.intellitrust.auth.model;

namespace Sample
{
    internal class AuthApiSample
    {
        private static readonly string HOST_NAME = "YOUR_HOST_NAME";
        private static readonly string APPLICATION_ID = "YOUR_APPLICATION_ID";

        public static void Main()
        {
            Configuration configuration = new Configuration();
            configuration.BasePath = HOST_NAME;

            var authApi = new AuthenticationApi(configuration);

            Console.WriteLine("Authenticating user");

            String userId = null;
            do
            {
                Console.WriteLine("Enter the User ID of existing user.");
                userId = Console.ReadLine().Trim();
            } while (userId == null || userId.Length == 0);

            String authType = null;
            do
            {
                Console.WriteLine("Enter the authentication type (PASSWORD, OTP, KBA, etc.)");
                authType = Console.ReadLine().Trim();
            } while (authType == null || authType.Length == 0);

            Console.WriteLine("Authenticating user " + userId);
            var challengeParams = new UserChallengeParameters(applicationId: APPLICATION_ID, userId: userId);
            AuthenticatedResponse challengeResponse = authApi.UserChallengeUsingPOST(authType, challengeParams);

            String response = null;
            do
            {
                Console.WriteLine("Enter the response");
                response = Console.ReadLine().Trim();
            } while (response == null || response.Length == 0);

            var authParams = new UserAuthenticateParameters(applicationId: APPLICATION_ID, response: response);
            try {
                authApi.UserAuthenticateUsingPOST(authType, authParams, challengeResponse.Token);
                Console.WriteLine("Authentication successful");
            } catch (ApiException e) {
                Console.WriteLine("Authentication failed: " + e.Message);
            }
        }
    }
}
```

**Python**

```python
from IntelliTrust_Python_Authentication import ApiClient, Configuration
import IntelliTrust_Python_Authentication.api as apis
import IntelliTrust_Python_Authentication.models as models
import IntelliTrust_Python_Authentication.exceptions as exceptions

conf = Configuration(host="YOUR_HOST_NAME")
with ApiClient(configuration=conf) as api_client:
    auth_api = apis.AuthenticationApi(api_client)
    auth_type = input("Enter the authentication type (PASSWORD, OTP, KBA, etc.): ")
    user_id = input("Enter the User ID of existing user: ")

    user_challenge_parameters = models.UserChallengeParameters(application_id=APPLICATION_ID, user_id=user_id)
    challenge_response = auth_api.user_challenge_using_post(auth_type, user_challenge_parameters)

    response = input("Enter response: ")
    user_authenticate_parameters = models.UserAuthenticateParameters(application_id=APPLICATION_ID, response=response)
    try:
        auth_response = auth_api.user_authenticate_using_post(auth_type, user_authenticate_parameters, challenge_response.token)
        if auth_response.authentication_completed:
            print("Authentication successful")
    except exceptions.ForbiddenException as e:
        print("Authentication failed: " + e.reason)
```

Sample code only

The sample code above is for demonstration purposes only. It is not intended to be used in production. Validate input parameters, handle exceptions, and use a secure method to set the application ID and host name.

## More guides

- For prerequisites, the three-call flow, and response fields, see [Authentication overview](/api/auth-api/core-concepts/authentication-overview.md).
- For PSD2, `offlineTVS`, and `pushMessageIdentifier`, see [Transaction details and mobile SDK push messages](/api/auth-api/core-concepts/transaction-details-and-push-messages.md).
- For risk evaluation behavior, see [Risk-based authentication and machine authentication](/api/auth-api/core-concepts/risk-based-authentication-and-machine-authentication.md).
- For authorization, token, device code, JWT IDaaS, and logout endpoints, see [OIDC and OAuth flows and endpoints](/api/auth-api/oidc-oauth/flows-and-endpoints.md).
- For raw HTTP walkthroughs, see [One-factor authentication](/api/auth-api/rest-examples/one-factor-authentication.md), [Two-factor authentication](/api/auth-api/rest-examples/two-factor-authentication.md), [External authentication with a second factor](/api/auth-api/rest-examples/external-plus-second-factor.md), [Risk-based authentication](/api/auth-api/rest-examples/risk-based-authentication.md), and [User logout](/api/auth-api/rest-examples/user-logout.md).
- For SDK-based examples, see [Get Users Authenticators](/api/auth-api/sdk-examples/get-users-authenticators.md), [One Time Password](/api/auth-api/sdk-examples/one-time-password.md), [Entrust Soft Token](/api/auth-api/sdk-examples/entrust-soft-token.md), and [Self passkey registration](/api/auth-api/sdk-examples/self-passkey-registration.md).
- For security scheme and support details, see [Authentication and support](/api/auth-api/core-concepts/authentication-and-support.md).