Sessions

A Session is a group of related events that belong to one continuous interaction between your end user and your system. In online, web and mobile contexts, a Session begins with a login and covers everything the user does until they log out. When you send Events to Alloy with a Session identifier, Alloy links those Events so your Workflows can evaluate each Event in the context of the Session it belongs to.

Sessions also let you share device data across Events. Device data that you send on one Event in a Session is available to later Events in the same Session.

What is a Session?

A Session is scoped to your Alloy account and is identified by the external_session_id that you assign to it. Every event that you send with the same external_session_id belongs to the same Session.

Sessions are different from Event Lifecycles. An Event Lifecycle (event_lifecycle_id) connects the statuses of a single event, such as one login that moves from attempted to successful. A Session connects different events from the same interaction, such as a login event, a person_updated event, and a transaction event. For more information, see Event Status & Lifecycles.

Session Identifiers

You can send external_session_id on any event type that you send to the Create an event endpoint. Include it at the top level of the data object.

{
    "event_type": "login",
    "event_status": "attempted",
    "event_lifecycle_id": "fabb00a8-ba1f-412d-8ecf-8bbaa578d6c2",
    "data": {
        "timestamp": "2024-03-25T23:50:34.681Z",
        "external_login_id": "fabb00a8-ba1f-412d-8ecf-8bbaa578d6c2",
        "external_session_id": "befdaf3c-86f8-4e1f-9c4c-06195fa08461",
        "external_entity_id": "9e82d5e7-ada0-4957-a8fd-4d937c99bae8",
        "username": "John.Doe84",
        "status": "attempted",
        "login_method": "password",
        "sso": null,
        "device": {
            "ip_address_v4": "88.232.60.238",
            "device_type": "mobile",
            "external_device_id": "38628f26-e16e-4a7d-a9c7-bc1e1ba55661"
        },
        "meta": {},
        "supplemental_data": {}
    }
}

{
    "status_code": 201,
    "event_request_token": "EV-vlm5H2TqSi8GyFT7ZaHB",
    "_links": {
        "self": {
            "href": "/v1/events/EV-vlm5H2TqSi8GyFT7ZaHB"
        }
    },
    "event": {
        "event_type": "login",
        "event_status": "PROCESSED",
        "data": {
            "timestamp": "2024-03-25T23:50:38.666Z",
            "external_entity_id": "9e82d5e7-ada0-4957-a8fd-4d937c99bae8",
            "username": "John.Doe84",
            "status": "attempted",
            "login_method": "password",
            "sso": null,
            "device": {
                "ip_address_v4": "88.232.60.238",
                "device_type": "mobile"
            },
            "meta": {
                "foo": "bar"
            },
            "supplemental_data": {},
            "entity_token": "P-TfkFe6lCPkElc9Xktd3V",
            "external_login_id": null
        },
        "evaluations": [],
        "journey_applications": []
    }
}

Session Identifier Best Practices

• Use one identifier for one interaction. Assign a new identifier to each login-to-logout window or call center contact. Don't reuse an identifier across unrelated interactions or across different end users.
• Match the session to your identity system. Alloy recommends sending a Session identifier that your customer identity and access management (CIAM) system assigns or recognizes about a user's actual login session. This mapping allows you to use Alloy to orchestrate Session termination or interdiction when an Event evaluates to a high-risk outcome.

Device Hydration across the Session

When an Event in a Session includes a device object, Alloy links that device data to the Session. Later Events in the same Session don't need to repeat it. If a later event includes the external_session_id but no device object, Alloy adds the Device data from the earlier event, so your Workflow can evaluate device-based rules on that event too.

This works for any event type, including several events of the same type. For example:

1. Send a login event with an external_session_id and a device object, as shown above.

2. Send a person_updated event with the same external_session_id and no device object:

   JSON

   {
     "event_type": "person_updated",
     "event_status": "successful",
     "data": {
       "timestamp": "2026-07-21T00:05:00.000Z",
       "external_session_id": "befdaf3c-86f8-4e1f-9c4c-06195fa08461",
       "external_entity_id": "9e82d5e7-ada0-4957-a8fd-4d937c99bae8"
     }
   }

   Because of the joining external_session_id, Alloy can evaluate the person_updated event with the device data from the login event

For more information on how Alloy identifies and stores Devices, see Identifying Devices.