---
title: Authenticate endpoint parameters
description: To authenticate to AM using REST, make an HTTP POST request to the json/authenticate endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/customers/realms/europe.
component: pingam
version: 7.2
page_id: pingam:authentication-guide: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
superseded_by: https://docs.pingidentity.com/pingam/8.1/am-authentication/authenticate-endpoint-parameters.html
---

# Authenticate endpoint parameters

To authenticate to AM using REST, make an HTTP POST request to the `json/authenticate` endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. 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 supported parameters:

* `authIndexType`

  Specifies the type of authentication the user will perform. Always use in conjunction with the `authIndexValue` parameter to provide additional information about the way the user is authenticating.

  If not specified, AM authenticates the user against the [default authentication service](core-module-conf-hints.html) configured for the realm.

  The `authIndexType` parameter supports the following types:

  * `composite_advice`

    Specifies that the value of the `authIndexValue` parameter is a URL-encoded composite advice string.

    Use `composite_advice` when you want to give AM hints of which authentication services to use when logging in a user. For example, use an authentication module that provides an authentication level of 10 or higher:

    ```bash
    $ curl -get \
    --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/realms/alpha/authenticate'
    ```

    The previous `curl` command URL-encodes the XML values, and the `-G` parameter appends them as query string parameters to the URL.

    |   |                                                     |
    | - | --------------------------------------------------- |
    |   | This example applies to authentication chains only. |

    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, see [Transactional authorization](../authorization-guide/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.

      |   |                                                       |
      | - | ----------------------------------------------------- |
      |   | This attribute applies to authentication chains only. |

      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`

    Specifies that the value of the `authIndexValue` parameter is 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'
    ```

  * `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'
    ```

    You should disable module-based authentication for security reasons. For more information, see [Secure realms](../security-guide/securing-realms.html).

  * `resource`

    Specifies that the value of the `authIndexValue` parameter is a URL protected by an AM policy.

    For example, to log into AM using a policy matching the `http://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'
    ```

    Note that the resource must be URL-encoded. Authentication will fail if no policy matches the resource.

  * `service`

    Specifies that the value of the `authIndexValue` parameter is the name of an authentication tree or authentication chain AM must use to log in the user.

    For example, to log in to AM using the built-in `ldapService` authentication chain, 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`

    Specifies that the value of the `authIndexValue` parameter is a valid user ID. AM will then authenticate the user against the chain configured in the User Authentication Configuration field of that user's profile.

    For example, for the user `demo` 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'
    ```

    Authentication will fail if the User Authentication Configuration field is empty for the user.

  If several authentication services that satisfy the authentication requirements are available, 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`

  Specifies the value of the `authIndexType` parameter.

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

* `noSession`

  When set to `true`, specifies that AM should not 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'
  {
      "message":"Authentication Successful",
      "successUrl":"/openam/console",
      "realm":"/"
  }
  ```

  Required: No.