Skip to main content
The Session endpoints allow administrators to list, retrieve, deactivate, and extend authentication sessions across all identities.

​
List all sessions

curl -X GET "https://{project}.projects.oryapis.com/admin/sessions?page_size=100&active=true" \
  -H "Authorization: Bearer ory_at_..."
List all sessions in the system with optional filtering and pagination.

​
Query parameters

​
page_size
integer
default:"250"
Number of items per page (min: 1, max: 1000).
​
page_token
string
Token for the next page of results. Returned in the Link header of previous responses.
​
active
boolean
Filter sessions by state:
  • true: Return only active sessions
  • false: Return only inactive sessions
  • Omitted: Return all sessions
​
expand
array
Expand related resources in the response:
  • identity: Include full identity object
  • devices: Include device history

​
Response

Returns an array of session objects:
​
id
string
Session UUID.
​
active
boolean
Whether the session is currently active.
​
authenticated_at
string
Timestamp when the session was authenticated (RFC3339 format).
​
expires_at
string
Timestamp when the session expires.
​
issued_at
string
Timestamp when the session was issued.
​
identity
object
The identity associated with this session (if expand=identity is set).
​
authenticator_assurance_level
string
AAL level: aal0, aal1, aal2, or aal3. Higher numbers indicate stronger authentication.
​
authentication_methods
array
Array of authentication methods used in this session.
​
devices
array
Device history for this session (if expand=devices is set).

​
Error responses

  • 400: Invalid query parameters

​
Get a session

curl -X GET "https://{project}.projects.oryapis.com/admin/sessions/{id}?expand=identity&expand=devices" \
  -H "Authorization: Bearer ory_at_..."
Retrieve a specific session by its ID with optional expansions.

​
Path parameters

​
id
string
required
The session’s UUID.

​
Query parameters

​
expand
array
Expand related resources:
  • identity: Include the full identity object
  • devices: Include device history for this session

​
Response

Returns a session object with the same structure as the list endpoint.

​
Error responses

  • 400: Invalid request parameters
  • 404: Session not found (may also indicate session doesn’t exist or has expired)

​
Deactivate a session

curl -X DELETE https://{project}.projects.oryapis.com/admin/sessions/{id} \
  -H "Authorization: Bearer ory_at_..."
Deactivate a session, logging out the user. Session data is preserved but the session becomes inactive.

​
Path parameters

​
id
string
required
The session’s UUID.

​
Response

Returns 204 No Content on success.

​
Error responses

  • 400: Invalid session ID format
  • 401: Unauthorized (invalid or missing access token)

​
Usage notes

Deactivating a session:
  • Sets the session’s active field to false
  • Invalidates any session tokens
  • Forces the user to re-authenticate
  • Does not delete the session record (use for audit purposes)
To delete all sessions for an identity, use the Delete Identity Sessions endpoint.

​
Extend a session

curl -X PATCH https://{project}.projects.oryapis.com/admin/sessions/{id}/extend \
  -H "Authorization: Bearer ory_at_..."
Extend the lifetime of a session. Honors the session.earliest_possible_extend configuration setting.

​
Path parameters

​
id
string
required
The session’s UUID.

​
Response

Returns 204 No Content on success. Some older Ory Network projects may return a 200 OK response with the updated session object in the body. This behavior is deprecated and should not be relied upon.

​
Error responses

  • 400: Invalid session ID or session cannot be extended yet
  • 404: Session not found or session was already extended recently

​
Usage notes

This endpoint:
  • Extends the session’s expires_at timestamp
  • Respects the session.earliest_possible_extend configuration
  • Returns 404 for consecutive requests to extend the same session
  • Does not modify the authenticated_at or issued_at timestamps

​
Configuration

To configure session extension behavior, see the session.lifespan and session.earliest_possible_extend settings in your Kratos configuration: 
session:
  lifespan: 24h
  earliest_possible_extend: 1h
With these settings:
  • Sessions last 24 hours from creation
  • Sessions can only be extended once they’re at least 1 hour old

​
Retrieving the session ID

To get a session ID for extension:
  1. Use the /sessions/whoami endpoint with a session token
  2. Use the Ory SDK’s toSession() method
  3. Query sessions via /admin/sessions or /admin/identities/{id}/sessions

​
Session lifecycle

Understanding session states:

​
Active session

  • active: true
  • expires_at is in the future
  • Valid session token exists
  • User is authenticated

​
Expired session

  • active: false (automatically set when expired)
  • expires_at is in the past
  • Session token is invalid
  • User must re-authenticate

​
Deactivated session

  • active: false (manually set via API)
  • May not be expired yet
  • Session token is invalidated
  • User must re-authenticate

​
Best practices

​
Monitoring sessions

  • Regularly query sessions with active=true to monitor active users
  • Use expand=devices to track login locations and devices
  • Monitor authenticator_assurance_level for security compliance

​
Security considerations

  • Deactivate sessions when suspicious activity is detected
  • Don’t extend sessions indefinitely - require periodic re-authentication
  • Track authentication_methods to ensure MFA compliance

​
Performance

  • Use pagination for large session lists
  • Only expand resources when needed
  • Cache session data with appropriate TTLs

Build docs developers (and LLMs) love

Get started for freeTalk to us