Session tokens after authentication

After successful authentication, PingOne Advanced Identity Cloud returns a tokenId that applications can present as a cookie value for other operations that require authentication. The tokenId contains a session token—a representation of the exchange of information and credentials between PingOne Advanced Identity Cloud and the user or identity.

If server-side sessions are enabled, the tokenId is a reference to the session state stored in the CTS token store.

The following is a common scenario when accessing PingOne Advanced Identity Cloud by using REST API calls:

Call the /json/authenticate endpoint to log a user in.

This call returns a tokenID value, which is used in subsequent calls to identify the user:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Secret12!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM...TU3OQ*",
    "successUrl": "/enduser/?realm=/alpha",
    "realm":"/alpha"
}

The returned tokenID is called a session token (also referred to as an SSO token). Each REST API call made after successful authentication must present the session token in the HTTP header as proof of authentication.

Call one or more additional REST APIs on behalf of the authenticated user.

Each REST API call passes the user’s tokenID back to PingOne Advanced Identity Cloud in the HTTP header as proof of previous authentication.

The following is a partial example of a curl command that inserts the token ID returned from a prior successful authentication attempt into the HTTP header:
```
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5w...NTcy*" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--data '{...}'
...
```
Observe that the session token is inserted into a header field named <session-cookie-name>. This header field name must correspond to the name of the tenant session cookie.

To find the name of the session cookie, refer to How do I view the tenant session cookie name?

Once a user has authenticated, you do not need to insert login credentials in the HTTP header in subsequent REST API calls. Note the absence of X-OpenAM-Username and X-OpenAM-Password headers in the preceding example.

Users must have appropriate privileges to access PingOne Advanced Identity Cloud functionality using the REST API.
Use the REST API to log the user out of PingOne Advanced Identity Cloud, as described in Log out using REST.

As with other REST API calls made after a user has authenticated, the REST API call to log out of PingOne Advanced Identity Cloud requires the user’s tokenID in the HTTP header.