Skip to main content

Low latency with session caching

Session caching is an Ory Network feature designed to ensure the lowest possible latency on the critical-path Check Session API, which includes the toSession and /sessions/whoami endpoints.

tip

Session caching is available for projects on the Business plan or higher. 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 ~60ms and a P99 latency of ~70ms across the globe when you use session caching. Results can vary depending on the geographical proximity to the closest node.

Impact on business logic​

There are some edge cases where 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, V0alpha2Api } from "@ory/client"

const ory = new V0alpha2Api(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, session caching is turned off for all projects. Follow these steps to turn the feature on:

To turn on session caching, go to Customize → Advanced Settings in the Ory Console.