Skip to main content

Refresh and Extend Sessions

For certain usecases, sessions need to be refreshed on user activity or administrative action.

When you refresh a session, its expires property is set to a value that is the time when the refresh is triggered plus the amount of time defined by the value of /session/lifespan.

Refresh Sessions as an Administrator​

To extend a session's lifespan, call the administrative adminRefreshSession endpoint with the session ID:

PATCH https://{your-project-slug-here}.projects.oryapis.com/admin/sessions/{id}/refresh
Authorization: Bearer {your-personal-access-token}
tip

To get the Session ID, call the /sessions/whoami endpoint or toSession.

Extend User Session Using the Admin Endpoints​

$ curl 'https://{your-project-slug}.projects.oryapis.com/admin/sessions/ede90ce6-2420-435a-a745-3d8ab1a9636c/extend' \
    -H 'Accept: application/json' | jq

{
  "id": "ede90ce6-2420-435a-a745-3d8ab1a9636c",
  "active": true,
  "expires_at": "2020-09-04T21:32:47.5642404Z",
  "authenticated_at": "2020-09-03T21:32:47.5881038Z",
  "issued_at": "2020-09-03T21:32:47.5642688Z",
  "identity": {
    "id": "d96e86d9-bc33-4aa5-b865-4ade8a3974b3",
    "schema_id": "default",
    "schema_url": "http://127.0.0.1:4433/schemas/default",
    "traits": {
      "email": "foouser@ory.sh",
      "name": {
        "first": "foo",
        "last": "user"
      }
    },
    "verifiable_addresses": [
      {
        "id": "81bbdeae-6333-42f2-877e-26c78acb6ea5",
        "value": "foouser@ory.sh",
        "verified": false,
        "via": "email",
        "status": "pending",
        "verified_at": null
      }
    ],
    "recovery_addresses": [
      {
        "id": "596c1db4-ccaa-4f4e-9623-cb7e768026ad",
        "value": "foouser@ory.sh",
        "via": "email"
      }
    ]
  }
}

Reduce Database Load​

Refreshing sessions causes database writes.

To reduce the database load, you can limit the time in which the session can be refreshed by adjusting the earliest_refresh configuration.

For example, if you set earliest_refresh to 24h, sessions can't be refreshed until 24 hours before they expire. This setting prevents putting excessive load on the database.

If you need high flexibility when extending sessions, you can set earliest_refresh to lifespan, which allows sessions to be refreshed during their entire lifespan, even right after they are created.

warning

If you set earliest_refresh to lifespan, all sessions will constantly be refreshed!

ory patch identity-config <your-project-id> \\
  --replace '/session/earliest_possible_extend="24h"'