---
title: Authenticate endpoint parameters
description: "Reference the authIndexType and authIndexValue parameters for PingAM's authenticate endpoint to specify authentication requirements including composite advice, authentication levels, modules, and..."
component: pingam
version: 7.5
page_id: pingam:am-authentication:authenticate-endpoint-parameters
canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/authenticate-endpoint-parameters.html
llms_txt: https://docs.pingidentity.com/pingam/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
keywords: ["Authentication", "Nodes & Trees", "REST API"]
page_aliases: ["authentication-guide:authenticate-endpoint-parameters.adoc"]
superseded_by: https://docs.pingidentity.com/pingam/8.1/am-authentication/authenticate-endpoint-parameters.html
section_ids:
  authindextype: authIndexType
  authindexvalue: authIndexValue
  nosession: noSession
---

# Authenticate endpoint parameters

To authenticate to AM using REST, send an HTTP POST request to the `json/authenticate` endpoint. Specify the realm hierarchy, starting at the Top Level Realm and prefix each realm in the hierarchy with the `realms/` keyword. For example, `/realms/root/realms/customers/realms/europe`.

The following list describes the `json/authenticate` endpoint parameters:

## `authIndexType`

The `authIndexType` specifies the type of authentication the user will perform. Always use this parameter in conjunction with the `authIndexValue` to provide additional information about how the user is authenticating.

If not specified, AM authenticates the user against the [default authentication service](realm-auth-config.html) configured for the realm.

The `authIndexType` can be one of the following:

* `composite_advice`

  When the `authIndexType` is `composite_advice`, the `authIndexValue` must be a URL-encoded composite advice string.

  Use the `composite_advice` type to indicate which authentication services to use when logging in a user.

  This example indicates that the user should authenticate with an authentication level of at least 10:

  ```bash
  $ curl -G \
  --request POST \
  --header "Content-Type: application/json" \
  --header 'Accept-API-Version: resource=2.0, protocol=1.0' \
  --data-urlencode 'authIndexType=composite_advice' \
  --data-urlencode 'authIndexValue=<Advices>
      <AttributeValuePair>
          <Attribute name="AuthLevelConditionAdvice"/>
          <Value>10</Value>
      </AttributeValuePair>
  </Advices>' \
  'https://openam.example.com:8443/openam/json/realms/root/authenticate'
  ```

  |   |                                                                                                                        |
  | - | ---------------------------------------------------------------------------------------------------------------------- |
  |   | This `curl` command URL-encodes the XML values. The `--get` option appends them as query string parameters to the URL. |

  Possible options for `Advices` are:

  * `TransactionConditionAdvice`. Requires the unique ID of a transaction token. For example:

    ```xml
    <Advices>
      <AttributeValuePair>
        <Attribute name="TransactionConditionAdvice"/>
        <Value>9dae2c80-fe7a-4a36-b57b-4fb1271b0687</Value>
      </AttributeValuePair>
    </Advices>
    ```

    For more information, refer to [Transactional authorization](../am-authorization/transactional-authorization.html).

  * `AuthenticateToServiceConditionAdvice`. Requires the name of an authentication chain or tree. For example:

    ```xml
    <Advices>
      <AttributeValuePair>
        <Attribute name="AuthenticateToServiceConditionAdvice"/>
        <Value>myExampleTree</Value>
      </AttributeValuePair>
    </Advices>
    ```

  * `AuthSchemeConditionAdvice`. Requires the name of an authentication module. For example:

    ```xml
    <Advices>
      <AttributeValuePair>
        <Attribute name="AuthSchemeConditionAdvice"/>
        <Value>DataStoreModule</Value>
      </AttributeValuePair>
    </Advices>
    ```

  * `AuthenticateToRealmConditionAdvice`. Requires the name of a realm. For example:

    ```xml
    <Advices>
      <AttributeValuePair>
        <Attribute name="AuthenticateToRealmConditionAdvice"/>
        <Value>myRealm</Value>
      </AttributeValuePair>
    </Advices>
    ```

  * `AuthLevelConditionAdvice`. Requires an authentication level.

    For example:

    ```xml
    <Advices>
      <AttributeValuePair>
        <Attribute name="AuthLevelConditionAdvice"/>
        <Value>10</Value>
      </AttributeValuePair>
    </Advices>
    ```

  * `AuthenticateToTreeConditionAdvice`. Requires the name of an authentication tree. For example:

    ```xml
    <Advices>
      <AttributeValuePair>
        <Attribute name="AuthenticateToTreeConditionAdvice"/>
        <Value>PersistentCookieTree</Value>
      </AttributeValuePair>
    </Advices>
    ```

  You can specify multiple advice conditions and combine them. For example:

  ```xml
  <Advices>
    <AttributeValuePair>
      <Attribute name="AuthenticateToServiceConditionAdvice"/>
      <Value>ldapService</Value>
    </AttributeValuePair>
    <AttributeValuePair>
      <Attribute name="AuthenticateToServiceConditionAdvice"/>
      <Value>Example</Value>
    </AttributeValuePair>
    <AttributeValuePair>
      <Attribute name="AuthLevelConditionAdvice"/>
      <Value>10</Value>
    </AttributeValuePair>
  </Advices>
  ```

* `level`

  When the `authIndexType` is `level`, the `authIndexValue` sets the minimum authentication level an authentication service must satisfy to log in the user.

  For example, to log into AM using an authentication service that provides a minimum authentication level of 10, you could use the following:

  ```bash
  $ curl \
  --request POST \
  --header 'Accept-API-Version: resource=2.0, protocol=1.0' \
  'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=level&authIndexValue=10'
  ```

  |   |                                                             |
  | - | ----------------------------------------------------------- |
  |   | This mechanism is supported for authentication chains only. |

* `module`

  Specifies that the value of the `authIndexValue` parameter is the name of the authentication module AM must use to log in the user.

  For example, to log into AM using the built-in `DataStore` authentication module, you could use the following:

  ```bash
  $ curl \
  --request POST \
  --header 'Accept-API-Version: resource=2.0, protocol=1.0' \
  'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=module&authIndexValue=DataStore'
  ```

  |   |                                                                                                                                                         |
  | - | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
  |   | For security reasons, you should disable module-based authentication. For more information, refer to [Secure realms](../security/securing-realms.html). |

* `resource`

  When the `authIndexType` is `resource`, the `authIndexValue` must be a URL protected by an AM policy.

  For example, to log into AM using a policy matching the `https://www.example.com` resource, you could use the following:

  ```bash
  $ curl \
  --request POST \
  --header 'Accept-API-Version: resource=2.0, protocol=1.0' \
  'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=resource&authIndexValue=https%3A%2F%2Fwww.example.com'
  ```

  The resource must be URL-encoded. Authentication fails if no policy matches the resource.

* `service`

  When the `authIndexType` is `service`, the `authIndexValue` is the tree or chain AM must use to authenticate the user.

  For example, to authenticate using the `Login` authentication tree, you could use the following:

  ```bash
  $ curl \
  --request POST \
  --header 'Accept-API-Version: resource=2.0, protocol=1.0' \
  'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Login'
  ```

  If `authIndexType=service` and no `authIndexValue` is specified, the default service is used. This is similar to no `authIndexType` being set.

* `user`

  When the `authIndexType` is `user`, the `authIndexValue` must be a valid user ID. AM authenticates the user against the authentication *chain* configured in the User Authentication Configuration field of that user's profile.

  Authentication fails if the User Authentication Configuration field is empty for the user.

  For example, for user `bjensen` to log into AM using the chain specified in their user profile, you could use the following:

  ```bash
  $ curl \
  --request POST \
  --header 'Accept-API-Version: resource=2.0, protocol=1.0' \
  'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=user&authIndexValue=bjensen'
  ```

  |   |                                                             |
  | - | ----------------------------------------------------------- |
  |   | This mechanism is supported for authentication chains only. |

  If there are several authentication services that satisfy the authentication requirements, AM presents them as a choice callback to the user. Return the required [callbacks](login-using-REST.html#login-callbacks) to AM to authenticate.

  Required: No.

## `authIndexValue`

This parameter sets a value for the specific `authIndexType`.

Required: Yes, when using the `authIndexType` parameter.

### `noSession`

When set to `true`, this parameter specifies that AM shouldn't return a session when authenticating a user.

For example:

```bash
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?noSession=true'
{
    "successUrl": "/openam/console",
    "realm": "/"
}
```

Required: No.

|   |                                                                                                                                                                                                       |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | If you use modules and chains, the success response includes a message. For example:```json
{
    "message": "Authentication Successful",
    "successUrl": "/openam/console",
    "realm": "/"
}
``` |