Session management

The session endpoints allow you to check authentication status, list active sessions, and revoke sessions for the authenticated user.

Get current session

curl -X GET 'https://your-project.projects.oryapis.com/sessions/whoami' \
  -H 'Cookie: ory_kratos_session=...' \
  -H 'Content-Type: application/json'

Check who the current HTTP session belongs to. This endpoint determines authentication by checking HTTP headers (cookies or bearer token).

Method and path

GET /sessions/whoami

Authentication

Authentication is determined by checking (in order):

Cookie header containing an Ory Kratos session cookie
Authorization: bearer <session-token> header
X-Session-Token header

Request parameters

tokenize_as

string

Returns the session additionally as a token (such as JWT). The value must be a valid, configured Ory Session token template. See session to JWT documentation for more information.

X-Session-Token

string

Session token for non-browser clients. Format: MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj

HTTP Cookie header. Required when calling from server-side applications to forward the session cookie. Example:

ory_kratos_session=a19iOVAbdzdgl70Rq1QZmrKmcjDtdsviCTZx7m9a9yHIUS8Wa9T7hvqyGTsLHi6Qifn2WUfpAKx9DWp0SJGleIn9vh2YF4A16id93kXFTgIgmwIOvbVAScyrx7yVl6bPZnCx27ec4WQDtaTewC1CpgudeDV2jQQnSaCP6ny3xa8qLH-QUgYqdQuoA_LF1phxgRCUfIrCLQOkolX5nv3ze_f==

Response

string

required

Session ID

active

boolean

Active state. If false, the session is no longer active.

expires_at

string

When this session expires

authenticated_at

string

When this session was authenticated. For multi-factor authentication, this is when the last factor was completed.

issued_at

string

When this session was issued. Usually equal or close to authenticated_at.

identity

object

The identity that owns this session

Show identity properties

string

Identity’s unique identifier

schema_id

string

ID of the JSON Schema used for validating the identity’s traits

schema_url

string

URL where the identity’s traits schema can be fetched

traits

object

The identity’s traits (e.g. email, name, phone number)

state

string

The identity’s state

authenticator_assurance_level

string

The authenticator assurance level. Higher numbers mean harder to compromise. aal1 means one factor was used, aal2 means two factors (e.g. password + TOTP).

authentication_methods

array

List of authenticators used during authentication

Show authentication method properties

method

string

The authentication method used

aal

string

Authenticator assurance level for this method

completed_at

string

When the authentication challenge was completed

provider

string

OIDC or SAML provider ID used for authentication

devices

array

History of all endpoints where the session was used

Show device properties

string

Device record ID

ip_address

string

IP address of the client

user_agent

string

User agent of the client

location

string

Geo location corresponding to the IP address

tokenized

string

The tokenized (e.g. JWT) version of the session. Only set when tokenize_as query parameter was provided.

Error responses

401

object

Unauthorized - No valid session found

403

object

Forbidden - Session has lower Authenticator Assurance Level (AAL) than possible for the identity. For example, the identity has password + webauthn credentials (AAL2) but the session only has AAL1.

Use cases

This endpoint is useful for:

AJAX calls - Remember to send credentials and configure CORS
Reverse proxies and API gateways - Validate sessions before forwarding requests
Server-side calls - Use the X-Session-Token header
Session verification - Check if a user is logged in

List active sessions

curl -X GET 'https://your-project.projects.oryapis.com/sessions' \
  -H 'Cookie: ory_kratos_session=...' \
  -H 'Content-Type: application/json'

Get all active sessions for the authenticated user, excluding the current session. To retrieve the current session, use /sessions/whoami.

Method and path

GET /sessions

Authentication

Requires authentication via Cookie or X-Session-Token header.

Request parameters

page_size

integer

default:"250"

Number of items per page (max: 500, min: 1)

page_token

string

Next page token for pagination. See pagination documentation.

per_page

integer

default:"250"

deprecated

Deprecated: Use page_token instead. This parameter will be removed in the future. Number of items per page (max: 1000, min: 1).

page

integer

deprecated

Deprecated: Use page_token instead. This parameter will be removed in the future. Page reference (not sequential).

X-Session-Token

string

Session token for non-browser clients. Format: MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj

HTTP Cookie header for forwarding session cookies from server-side applications

Response

Returns an array of session objects. Each session has the same structure as the /sessions/whoami response.

[
  {
    "id": "e3c48c1e-62a0-4a8a-9b3e-1f9c7d5e2b4a",
    "active": true,
    "expires_at": "2026-03-10T15:30:00Z",
    "authenticated_at": "2026-03-03T15:30:00Z",
    "issued_at": "2026-03-03T15:30:00Z",
    "identity": {
      "id": "9f3b2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "schema_id": "default",
      "traits": {
        "email": "[email protected]"
      }
    },
    "authenticator_assurance_level": "aal1",
    "devices": [
      {
        "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
        "ip_address": "192.168.1.1",
        "user_agent": "Mozilla/5.0...",
        "location": "San Francisco, CA"
      }
    ]
  }
]

Error responses

400

object

Bad Request - Invalid pagination parameters

401

object

Unauthorized - No valid session found

Revoke a session

curl -X DELETE 'https://your-project.projects.oryapis.com/sessions/{id}' \
  -H 'Cookie: ory_kratos_session=...' \
  -H 'Content-Type: application/json'

Invalidate a specific session. The current session cannot be revoked using this endpoint. Session data is not deleted, only the session is marked as inactive.

Method and path

DELETE /sessions/{id}

Authentication

Requires authentication via Cookie or X-Session-Token header.

Request parameters

string

required

The session ID to revoke

X-Session-Token

string

Session token for non-browser clients

HTTP Cookie header for forwarding session cookies

Response

Returns HTTP 204 No Content on success.

Error responses

400

object

Bad Request - Cannot revoke current session or invalid session ID

401

object

Unauthorized - No valid session found

Revoke all other sessions

curl -X DELETE 'https://your-project.projects.oryapis.com/sessions' \
  -H 'Cookie: ory_kratos_session=...' \
  -H 'Content-Type: application/json'

Invalidate all sessions except the current one. Useful for implementing “log out from all other devices” functionality.

Method and path

DELETE /sessions

Authentication

Requires authentication via Cookie or X-Session-Token header.

Request parameters

X-Session-Token

string

Session token for non-browser clients

HTTP Cookie header for forwarding session cookies

Response

count

integer

The number of sessions that were revoked

{
  "count": 3
}

Error responses

400

object

Bad Request

401

object

Unauthorized - No valid session found

Exchange session token

curl -X GET 'https://your-project.projects.oryapis.com/sessions/token-exchange?init_code=abc123&return_to_code=def456' \
  -H 'Content-Type: application/json'

Exchange session token codes for a complete session token. This is part of the native app flow where codes are split between the initialization and return URL.

Method and path

GET /sessions/token-exchange

Authentication

No authentication required (the codes serve as authentication).

Request parameters

init_code

string

required

The part of the code returned when initializing the flow

return_to_code

string

required

The part of the code returned by the return_to URL

Response

session

object

required

The session object

session_token

string

A session token equivalent to a session cookie. Can be sent in the HTTP Authorization header: Authorization: bearer ${session-token}. Only issued for API flows, not browser flows.

continue_with

array

List of actions that could follow this flow (e.g., verification flow reference)

{
  "session": {
    "id": "e3c48c1e-62a0-4a8a-9b3e-1f9c7d5e2b4a",
    "active": true,
    "identity": {
      "id": "9f3b2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "traits": {
        "email": "[email protected]"
      }
    }
  },
  "session_token": "MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj"
}

Error responses

403

object

Forbidden - Invalid codes

404

object

Not Found - Code exchange not found

410

object

Gone - Code exchange expired

Admin API

Self-Service API

Frontend API

Get current session

Method and path

Authentication

Request parameters

Response

Error responses

Use cases

List active sessions

Method and path

Authentication

Request parameters

Response

Error responses

Revoke a session

Method and path

Authentication

Request parameters

Response

Error responses

Revoke all other sessions

Method and path

Authentication

Request parameters

Response

Error responses

Exchange session token

Method and path

Authentication

Request parameters

Response

Error responses

Build docs developers (and LLMs) love

Admin API

Self-Service API

Frontend API

​Get current session

​Method and path

​Authentication

​Request parameters

​Response

​Error responses

​Use cases

​List active sessions

​Method and path

​Authentication

​Request parameters

​Response

​Error responses

​Revoke a session

​Method and path

​Authentication

​Request parameters

​Response

​Error responses

​Revoke all other sessions

​Method and path

​Authentication

​Request parameters

​Response

​Error responses

​Exchange session token

​Method and path

​Authentication

​Request parameters

​Response

​Error responses

Build docs developers (and LLMs) love

Get current session

Method and path

Authentication

Request parameters

Response

Error responses

Use cases

List active sessions

Method and path

Authentication

Request parameters

Response

Error responses

Revoke a session

Method and path

Authentication

Request parameters

Response

Error responses

Revoke all other sessions

Method and path

Authentication

Request parameters

Response

Error responses

Exchange session token

Method and path

Authentication

Request parameters

Response

Error responses