There are a couple of endpoints available to manage Hosted Login sessions administratively. They allow you to:

• Find a session for a particular user
• View information about a session
• Delete a session, which ends the session across all devices

Session management endpoints

The administrative endpoints are:

• /sessions?sub={user-urn}
• /sessions/{session-id}

The base URL for these endpoints is the region-specific URL you were given when your Identity Cloud instance was created, and is the same base URL used for other Hosted Login and configuration endpoints. It looks like this:

https://v1.api.eu.janrain.com

A full endpoint looks like this:

https://v1.api.eu.janrain.com/sessions/12345abc-678d-9ef0-gh12-3i45jk6l7mn8

Request methods & headers

Hosted Login sessions can be found, viewed, or deleted depending on the endpoint called and the HTTP request method used. See the table below for details:

Like other Identity Cloud and Hosted Login configuration endpoints, these endpoints use token-based authentication. This means you must retrieve an administrative access token with adequate scope(s) to pass into the Authorization header. (See the Minimum required auth scope column in the table above for reference.)

To identify your Identity Cloud instance to configure, you must pass your customer ID into the Tenant-ID header.

📘

All /sessions endpoints support passing the customer ID in either the Tenant-ID header or directly in the endpoint path, like this:

https://v1.api.eu.janrain.com/{customer-id}/sessions

Constructing the User URN

To find a session for a specific user, you must pass the Identity Cloud Uniform Resource Name (URN) for that user into the /sessions endpoint.

📘

The URN format is an internet standard (RFC 8141) that allows the Identity Cloud platform to identify a resource globally, regardless of region, protocol, or API.

The user URN is passed into a URL parameter called sub.

Example:

https://v1.api.eu.janrain.com/sessions
  ?sub=urn:akamai-ic:IRL:capture:entity:MEYWEY3EMUZGMZZTNA2DKNTJNJVTO3BYNVXG64BZOEXXK43FOIXTOMRWGA4DOZLDFUZTKZDGFU2DANBRFVQWKYZYFVRTCMLFMNRTEMBYMVTGC

👍

The user URN is found in all session-related webhook event payloads.
It is the "subject" attribute. (See example payload under Track session activity.)

To construct the user URN, you’ll need the following pieces of information:

• The ISO 3166-1 alpha-3 country code corresponding to your Identity Cloud region. For example:
  • EU region = IRL
  • JP region = JPN
  • US region = USA
• Your Identity Cloud Application ID (example: a1bcde2fg3h456ijk7l8mnop9q)
• The name of the Entity Type where this user is stored (example: user)
• The user’s UUID (example: 726087ec-35df-4041-aec8-c11ecc208efa)

Steps to construct the user URN using the information above:

1. Join the Application ID, Entity Type name, and UUID (in that order) with a forward slash (/) in between: {app-id}/{entity-type}/{uuid}

   Example:

   a1bcde2fg3h456ijk7l8mnop9q/user/726087ec-35df-4041-aec8-c11ecc208efa
   

   👍

   The same string is found in the global_sub, where it is the last 3 segments in the path.

   Example: "global_sub": "capture-v1://eu-dev.janraincapture.com/a1bcde2fg3h456ijk7l8mnop9q/user/726087ec-35df-4041-aec8-c11ecc208efa"

2. Base32 encode this string, without padding (remove any trailing = after encoding)

   Example:

   MEYWEY3EMUZGMZZTNA2DKNTJNJVTO3BYNVXG64BZOEXXK43FOIXTOMRWGA4DOZLDFUZTKZDGFU2DANBRFVQWKYZYFVRTCMLFMNRTEMBYMVTGC
   

   👍

   Tips:

   • Base32 encoding (with or without padding) should be available in most major programming languages, or is easily implemented following the Base32 standard.
   • Ad-hoc encoding/decoding for quick testing purposes can be done on websites like DenCode (and there are many, many more).

3. Add the encoded string, along with your ISO country code, into the following URN format: urn:akamai-ic:{iso-region}:capture:entity:{encoded-string}

   Example:

   urn:akamai-ic:IRL:capture:entity:MEYWEY3EMUZGMZZTNA2DKNTJNJVTO3BYNVXG64BZOEXXK43FOIXTOMRWGA4DOZLDFUZTKZDGFU2DANBRFVQWKYZYFVRTCMLFMNRTEMBYMVTGC
   

Example API calls

Find session by user

curl --location --request GET 'https://v1.api.eu.janrain.com/sessions?sub=urn%3Aakamai-ic%3AIRL%3Acapture%3Aentity%3AMEYWEY3EMUZGMZZTNA2DKNTJNJVTO3BYNVXG64BZOEXXK43FOIXTOMRWGA4DOZLDFUZTKZDGFU2DANBRFVQWKYZYFVRTCMLFMNRTEMBYMVTGC' \
--header 'Tenant-ID: a12bc34d-567e-8f90-gh12-3i45jk678lm9' \
--header 'Authorization: Bearer xk_t4lAQzpjJVTGhpNh2fdhtRsgPUJXaQuYS0KXEiQzttEKNHU7WLpT4eSyxzoDB' 

Example response when there is a valid session: 200 OK

{
    "total": 1,
    "_links": {
        "self": {
            "href": "/sessions?sub=urn:akamai-ic:IRL:capture:entity:MEYWEY3EMUZGMZZTNA2DKNTJNJVTO3BYNVXG64BZOEXXK43FOIXTOMRWGA4DOZLDFUZTKZDGFU2DANBRFVQWKYZYFVRTCMLFMNRTEMBYMVTGC"
        },
        "item": [
            {
                "href": "/sessions/2cfd6334-12ef-4bee-9365-6f918ad1e56b"
            }
        ]
    }
}

🚧

Note the session ID (sid) in the example response above (2cfd6334-12ef-4bee-9365-6f918ad1e56b).

Example response when there is no session: 200 OK

{
    "total": 0,
    "_links": {
        "self": {
            "href": "/sessions?sub=urn:akamai-ic:IRL:capture:entity:MEYWEY3EMUZGMZZTNA2DKNTJNJVTO3BYNVXG64BZOEXXK43FOIXTOMRWGA4DOZLDFUZTKZDGFU2DANBRFVQWKYZYFVRTCMLFMNRTEMBYMVTGC"
        }
    }
}

View session information

curl --location --request GET 'https://v1.api.eu.janrain.com/sessions/2cfd6334-12ef-4bee-9365-6f918ad1e56b' \
--header 'Tenant-ID: a12bc34d-567e-8f90-gh12-3i45jk678lm9' \
--header 'Authorization: Bearer xk_t4lAQzpjJVTGhpNh2fdhtRsgPUJXaQuYS0KXEiQzttEKNHU7WLpT4eSyxzoDB' 

📘

The session ID (sid) passed into this call can come from a number of places, such as:

• The response from a previous call to the /sessions?sub={user-urn} endpoint (see example above)
• The "sid" from a session-related webhook event payload
• The "sid" from an OIDC ID token

Example response when the session is valid: 200 OK

{
    "id": "2cfd6334-12ef-4bee-9365-6f918ad1e56b",
    "age": 694,
    "lastActivityAt": "2023-09-26T19:26:23.886780106Z",
    "subject": "urn:akamai-ic:IRL:capture:entity:MEYWEY3EMUZGMZZTNA2DKNTJNJVTO3BYNVXG64BZOEXXK43FOIXTOMRWGA4DOZLDFUZTKZDGFU2DANBRFVQWKYZYFVRTCMLFMNRTEMBYMVTGC"
}

Response when the session is invalid: 404 Not Found

Delete session

curl --location --request DELETE 'https://v1.api.eu.janrain.com/sessions/2cfd6334-12ef-4bee-9365-6f918ad1e56b' \
--header 'Tenant-ID: a12bc34d-567e-8f90-gh12-3i45jk678lm9' \
--header 'Authorization: Bearer xk_t4lAQzpjJVTGhpNh2fdhtRsgPUJXaQuYS0KXEiQzttEKNHU7WLpT4eSyxzoDB'

Success response: 204 No Content

📘

The success response is the same (204 No Content) regardless of whether this call deleted the session, or the session was previously deleted.