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

There are some cases where edge session caching can affect your business logic:

• Changes made to sessions or their corresponding identities through the admin API will not be immediately reflected in the /session/whoami endpoint.

  info

  The Check Session APIs are eventually consistent, which means that the changes you make are always reflected in the API, even if in some cases this might not be instantaneous.

• In some scenarios, revoked sessions will not immediately be marked as inactive by the /session/whoami endpoint.

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

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

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