Low latency with Edge Sessions

Edge Sessions is a caching mechanism in Ory Network that's designed to ensure the lowest possible latency on the critical-path Check Session API, which includes the toSession and /sessions/whoami endpoints. With Edge Sessions enabled, the system uses smart caching strategies to validate sessions at edge nodes that are reachable within 100ms for 95% of the world's population.

tip

Edge Sessions is a feature available on all paid plans. You must enable this feature manually. Read the Configuration section to learn how to turn it on.

Caching strategy

The /sessions/whoami endpoint is optimized for maximum performance and low latency when using Ory Session Cookies. To achieve this, Ory uses a planet-scale network edge cache.

The caching strategy is as follows:

• If the session credentials are unknown, the cache is bypassed.
• If the session credentials are known and cached, the cache is served immediately and refreshed in the background.
• If the session credentials are known and cached, the cache respects the Cache-Control: max-age=60 header.
• If the user updates their profile or adds another authentication factor, the session is refreshed in the cache automatically.

Performance

You can expect a P95 latency of ~35ms and a P99 latency of ~45ms across the globe when you use edge sessions. Results can vary depending on the geographical proximity to the closest node.

Impact on business logic

The Check Session API is eventually consistent when Edge Caching is enabled, which means that the changes you make are always reflected in the API, even if in some cases this might not be instantaneous. There are some cases where edge session caching will affect your business logic.

info

Per default, the session's cache time is set to 2 minutes and 30 seconds.

You can modify this value in the Ory Console or using the Ory CLI (see the Configuration section).

The longer the cache time, the more likely it is that the session data is outdated at the benefit of faster API responses. The shorter the cache time, the more likely it is that the session data is fresh at the expense of slower API responses.

• Changes made to sessions or their corresponding identities through the admin API will not be immediately reflected in the /session/whoami endpoint.
• When revoking a session using the Ory Console or the admin API, the session will be marked as inactive immediately. However, the /session/whoami endpoint might still return the session as active for a short period of time.
• The hook to disable all sessions after a password change will mark all sessions as inactive immediately. However, the /session/whoami endpoint might still return the session as active for a short period of time.
• Sessions modified by the user (e.g. performing second factor authentication, logging out, refreshing the session) will be reflected in the /session/whoami endpoint immediately without delay.

Force refresh

You can force the /session/whoami API to bypass the cache and to return a fresh response by setting Cache-Control: max-age=0.

note

Bypassing the cache significantly increases response latencies. Try to avoid Cache-Control: max-age=0 and use the cache as much as possible.

This will always fetch the freshest session data available and can be used in APIs where you need up-to-date data:

import { Configuration, FrontendApi } from "@ory/client"

const ory = new FrontendApi(new Configuration())

ory.toSession(undefined, undefined, {
  headers: {
    "Cache-Control": "max-age=0",
  },
})

The max-age defines what the maximum age of the cache can be. If you set it to 10, the server will reply with a cached response if the cache is no older than 10 seconds:

ory.toSession(undefined, undefined, {
  headers: {
    "Cache-Control": "max-age=10",
  },
})

Configuration

By default, the Edge Sessions feature is turned off for all projects. Follow these steps to turn the feature on:

Ory Console

To turn on Edge Sessions, go to Authentication → Sessions in the Ory Console.

Ory CLI

1. Download the Ory Identities config from your project and save it to a file:

   ## List all available projects
   ory list projects
   
   ## Get config
   ory get identity-config {project-id} --format yaml > identity-config.yaml

2. Add the configuration for Edge Sessions:

   config.yml

   feature_flags:
     cacheable_sessions: true
     cacheable_sessions_max_age: "1m"

3. Update the Ory Identities configuration using the file you worked with:

   ory update identity-config {project-id} --file identity-config.yaml