> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn about managing sessions with Actions

# Sessions with Actions

Using Sessions with [Actions](/docs/customize/actions) allows you to configure post-authentication risk detection and response capabilities to protect your applications and users against session hijacking. You can also dynamically customize the [session lifetime limits](/docs/manage-users/sessions/configure-session-lifetime-settings).

To facilitate this, post-login Actions feature two key objects:

* **event.session**: Provides relevant information including unique `id`, `created_at`, `expires_at`, `idle_expires_at`, `updated_at` dates, `clients`, `authentication_at`, and `device` information, such as `ASN`, `IP`, and `User_agent`.
* **api.session:** Allows you to manage existing sessions by revoking sessions or changing `expiry` dates.

The `event.session` and `api.session` objects both support interactive web-based flows, including [authorization code flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow), implicit flow, device code flow, as well as <Tooltip tip="Security Assertion Markup Language (SAML): Standardized protocol allowing two parties to exchange authentication information without a password." cta="View Glossary" href="/docs/glossary?term=SAML">SAML</Tooltip> and <Tooltip tip="Security Assertion Markup Language (SAML): Standardized protocol allowing two parties to exchange authentication information without a password." cta="View Glossary" href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip>.

You can use the `event.session` object to review timestamps of the latest interactions and evaluate risks associated with the current transactions. You can also combine the `event.session` object with other event objects, such as `event.authentication` or `event.request`.

You can then use the `api.session` object to either reset the existing session expiry dates or revoke the session.

To learn more about these objects, review:

* [Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): Learn about the session Event object and properties.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object): Learn about the session API object and methods.

## Revoke sessions with Actions

The post-login **api.session.revoke(reason, options)** method allows you to react to risks associated with a transaction. This method includes an option to allow you to preserve the <Tooltip tip="Refresh Token: Token used to obtain a renewed Access Token without forcing users to log in again." cta="View Glossary" href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> bound to the revoked transaction.

In addition to revoking the session, the method will also initiate a `session-revoked` [OIDC Back-Channel Logout Initiator](/docs/authenticate/login/logout/back-channel-logout/oidc-back-channel-logout-initiators) to log out users from all applications bound to the current session and log a [session\_revoked](/docs/deploy-monitor/logs/log-event-type-codes) event in the tenant logs.

You can use this method to:

* Invalidate the current session transaction in Auth0
* Deny the current transaction
* Revoke all [refresh tokens](/docs/secure/tokens/refresh-tokens) associated with the existing session with a matching `session_id` value.

  * This is a customizable option; you can choose to preserve the refresh tokens rather than revoke them. This operation runs asynchronously and eventually becomes consistent.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  If you want to use the `api.session.revoke(reason,options)` method, ensure that the property event.session.id exists.

  Different from `api.access.deny()`, `api.session.revoke()` will deny the current transaction and also revoke the session, therefore first factor authentication will be required again
</Callout>

### Monitor revoke log events

The revoke operation adds the following log event in your [tenant logs](/docs/deploy-monitor/logs):

A `session_revoked` event code indicating a revoked session with its associated `session_id` attribute.

## Change sessions expiry dates with Actions

You can modify session [expiry dates](/docs/manage-users/sessions/session-lifetime-limits) with the following post-login methods:

* **api.session.setExpiresAt(absolute)** allows you to define a new absolute (Require log in after) session expiration date for a specified session.
* **api.session.setIdleExpiresAt(idle)** allows you to set a new inactivity timeout date for a specified session.

You can use these methods to dynamically customize the session lifetime and inactivity policies based on:

* A user’s organization
* A user’s Auth0 connection
* A specific user’s group membership or profile
* Risk assessment
* Any other dynamic criteria available during the execution of the Action

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  If you want to use the `api.session.setExpiresAt(absolute)` and `api.session.setIdleExpiresAt(idle)` methods, ensure that a property of the event.session object exists, such as `event.session.id`.

  The `api.session.setIdleExpiresAt(idle)` method sets the session inactivity timeout for  the current interaction. If the method is not reapplied, subsequent successful interactions will override the inactivity timeout using the session inactivity timeout settings.
</Callout>

## Set session cookie persistence with Actions

The post-login **api.session.setCookieMode(options)** method allows you to modify the session cookie persistence. You can configure whether a session cookie is persistent or non-persistent.

Non-persistent (ephemeral) sessions enhance security by existing only in memory. These sessions are cleared when a browser or application is closed, which makes them ideal for sensitive workflows such as untrusted device access or step-up authentication scenarios.

You can use this method to:

* Enforce ephemeral sessions for users in high-risk roles or groups

* Require reauthentication when the browser is closed for certain devices or IP ranges

* Shorten session lifespan for untrusted or shared environments (e.g., public computers)

This method accepts the following parameters:

| Property         | Type   | Description                                                                                          |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `persistent`     | string | The session is stored in a persistent cookie and survives browser restarts, unless manually cleared. |
| `non-persistent` | string | The session is stored in memory only and cleared when the browser or application is closed.          |

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The `api.session.setCookieMode()` method overrides the default tenant setting for the current session.

  Auth0 retains the persistence setting throughout the session and does not need to be set again in future silent authentication flows.

  The `api.session.setCookieMode()` method must be used within a post-login Action. If it is used in a context where `api.session` is not available, the call fails silently.
</Callout>

To learn how to implement session cookie persistence, read [Configure Keep Me Signed In using Sessions](/docs/manage-users/sessions/configure-keep-me-signed-in-sessions).

## Limitations

Sessions issued before the release of the post-login API methods `api.session.setExpiresAt(absolute)` and `api.session.setIdleExpiresAt(idle)` will not contain the following event.session property: `last_interacted_at.`

Sessions issued before the release of the post-login API method `api.session.revoke(reason, options)` will not contain the following event.session.device properties:

* `initial_ip`
* `initial_asn`
* `initial_user_agent`

For security reasons, inactivity and absolute timeouts cannot be set above the session settings defined in the [session lifetime limits](/docs/manage-users/sessions/configure-session-lifetime-settings) for the tenant. If you attempt to set a date above the lifetime limits, the API methods will update up to the lifetime limits and log a warning event (`w`) in the tenant logs.

## Use cases: Revoke a session

You can use [Actions](/docs/customize/actions) to configure risk detections and revoke risky sessions and their associated refresh tokens with the post-login `api.session.revoke(reason, options)` method and the `event.session` object.

### Revoke a session due to ASN network binding

You can use the post-login object properties, `event.session.device.initial_asn` and `event.request.asn` to bind session transactions to a specific [autonomous system number (ASN)](https://www.arin.net/resources/guide/asn/) network for their duration and require a re-authentication if the ASN network changes.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const sessionInitialAsn = event.session?.device?.initial_asn;
  const sessionCurrentAsn = event.request.asn;

  // if there is a session and the ASN changes
  if (
    sessionInitialAsn &&
    sessionCurrentAsn &&
    sessionInitialAsn != sessionCurrentAsn
  ) {
    api.session.revoke( "Invalid network change. Login again from a trusted network" )
  }
};
```

In this example, a check occurs at the start of the Action to verify that the `event.session.device.initial_asn` and `event.request.asn` properties remain within the same ASN network during the transaction. If this check fails, the Action calls  `api.session.revoke()` to:

* Invalidate the session
* Deny the current transaction
* Revoke all its associated refresh tokens
* Prompt for re-authentication

### Revoke a session due to an IP binding

You can use the post-login object properties `event.session.device.initial_ip` and `event.request.ip` to ensure a session transaction stays with the same IP address for its duration. In this scenario, any IP change is considered a risk, and the user will be prompted to re-authenticate.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const sessionInitialIp = event.session?.device?.initial_ip;
  const sessionCurrentIp = event.request.ip;

  // if there is a session and the IP changes
  if (
    sessionInitialIp &&
    sessionCurrentIp &&
    sessionInitialIp != sessionCurrentIp
  ) {
    api.session.revoke("Invalid IP change")
  }
};
```

In this example, a check occurs at the start of the Action to verify that the `event.session.device.initial_ip` and `event.request.ip` properties remain with the same IP address during the transaction. If the check fails, the Action then calls  `api.session.revoke()` to:

* Invalidate the session
* Deny the current transaction
* Revoke all its associated refresh tokens
* Prompt for re-authentication

## Use cases: Customize a session expiry dates

You can use [Actions](/docs/customize/actions) to customize session idle and absolute expiration dates. Specifically, you can configure the expiry dates for a particular session transaction using the post-login `api.session.setExpiresAt(absolute)` and `api.session.setIdleExpiresAt(idle)` methods and the `event.session` object.

### Customize absolute session expiration time based on connections

You can use the following post-login object properties, to define a lifetime for the connection used to authenticate a user.

* event.session.created\_at
* event.session.expires\_at

And using the Auth0 [Management API](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) to create a connection metadata , `event.connection.metadata.session_timeout define` a specific connection timeout.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const created = Date.parse(event.session?.created_at ?? "");

  // desired session lifetime for this connection in milliseconds, configured as connection metadata
  const connection_lifetime = event.connection?.metadata?.session_timeout;

  // if there is a session lifetime defined for the connection, set it
  if (event.session?.id && connection_lifetime) {
    api.session.setExpiresAt(created + Number(connection_lifetime));
  }
};
```

In this example, a check occurs at the start of the Action to verify that there is a  `session_timeout` defined in the current connection. In that case, the Action sets the session expiration to be equal to when the session was `created` plus the `connection_lifetime`.

### Customize session inactivity timeout based on the Organization

You can define a `current_time` variable and using a new Organization metadata called `idle_session_timeout` set the idle timeout desired for an organization.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // The Organization metadata is configured with a shorter idle timeout for sessions (in milliseconds)
  const idle_organization_lifetime =
    event.organization?.metadata?.idle_session_timeout;

  // If the organization has an specific idle timeout defined, set the timeout
  if (event.session?.id && idle_organization_lifetime) {
    const current_time = new Date().getTime();

    api.session.setIdleExpiresAt(
      current_time + Number(idle_organization_lifetime),
    );
  }
};
```

In this example, if there is a specific idle timeout defined for the Organization, the Action sets the session inactivity timeout to be equal to the `current_time` plus the `idle_organization_lifetime` .