Clerk docs

Sessions

The Session object is an abstraction over an HTTP session. It models the period of information exchange between a user and the server. Sessions are created when a user successfully goes through the sign in or sign up flows.

https://clerk.com/docs/reference/clerkjs/session

List all sessions

Returns a list of all sessions. The sessions are returned sorted by creation date, with the newest sessions appearing first. Deprecation Notice (2024-01-01): All parameters were initially considered optional, however moving forward at least one of client_id or user_id parameters should be provided.

SecuritybearerAuth
Request
query Parameters
client_id
string

List sessions for the given client

user_id
string

List sessions for the given user

status
string

Filter sessions by the provided status

Enum: "abandoned" "active" "ended" "expired" "removed" "replaced" "revoked"
paginated
boolean

Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.

limit
integer [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset.

offset
integer >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

Responses
200

Success

400

Request was not successful

401

Authentication invalid

422

Invalid request parameters

get/sessions
Response samples
application/json
[
  • {
    }
]

Create a new active session

Create a new active session for the provided user ID.

This operation is intended only for use in testing, and is not available for production instances. If you are looking to generate a user session from the backend, we recommend using the Sign-in Tokens resource instead.

SecuritybearerAuth
Request
Request Body schema: application/json
user_id
required
string

The ID representing the user

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Request was not successful

422

Invalid request parameters

post/sessions
Request samples
application/json
{
  • "user_id": "string"
}
Response samples
application/json
{
  • "object": "session",
  • "id": "string",
  • "user_id": "string",
  • "client_id": "string",
  • "actor": { },
  • "status": "active",
  • "last_active_organization_id": "string",
  • "last_active_at": 0,
  • "latest_activity": {
    },
  • "expire_at": 0,
  • "abandon_at": 0,
  • "updated_at": 0,
  • "created_at": 0
}

Retrieve a session

Retrieve the details of a session

SecuritybearerAuth
Request
path Parameters
session_id
required
string

The ID of the session

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Resource not found

get/sessions/{session_id}
Response samples
application/json
{
  • "object": "session",
  • "id": "string",
  • "user_id": "string",
  • "client_id": "string",
  • "actor": { },
  • "status": "active",
  • "last_active_organization_id": "string",
  • "last_active_at": 0,
  • "latest_activity": {
    },
  • "expire_at": 0,
  • "abandon_at": 0,
  • "updated_at": 0,
  • "created_at": 0
}

Refresh a session

Refreshes a session by creating a new session token. A 401 is returned when there are validation errors, which signals the SDKs to fallback to the handshake flow.

SecuritybearerAuth
Request
path Parameters
session_id
required
string

The ID of the session

Request Body schema: application/json

Refresh session parameters

expired_token
required
string

The JWT that is sent via the __session cookie from your frontend. Note: this JWT must be associated with the supplied session ID.

refresh_token
required
string

The JWT that is sent via the __session cookie from your frontend.

request_origin
required
string

The origin of the request.

object or null

The headers of the request.

format
string or null
Default: "token"

The format of the response.

Enum: "token" "cookie"
request_originating_ip
string or null

The IP address of the request.

Responses
200

Success

400

Request was not successful

401

Authentication invalid

post/sessions/{session_id}/refresh
Request samples
application/json
{
  • "expired_token": "string",
  • "refresh_token": "string",
  • "request_origin": "string",
  • "request_headers": { },
  • "format": "token",
  • "request_originating_ip": "string"
}
Response samples
application/json
{
  • "object": "token",
  • "jwt": "string"
}

Revoke a session

Sets the status of a session as "revoked", which is an unauthenticated state. In multi-session mode, a revoked session will still be returned along with its client object, however the user will need to sign in again.

SecuritybearerAuth
Request
path Parameters
session_id
required
string

The ID of the session

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Resource not found

post/sessions/{session_id}/revoke
Response samples
application/json
{
  • "object": "session",
  • "id": "string",
  • "user_id": "string",
  • "client_id": "string",
  • "actor": { },
  • "status": "active",
  • "last_active_organization_id": "string",
  • "last_active_at": 0,
  • "latest_activity": {
    },
  • "expire_at": 0,
  • "abandon_at": 0,
  • "updated_at": 0,
  • "created_at": 0
}

Verify a sessionDeprecated

Returns the session if it is authenticated, otherwise returns an error. WARNING: This endpoint is deprecated and will be removed in future versions. We strongly recommend switching to networkless verification using short-lived session tokens, which is implemented transparently in all recent SDK versions (e.g. NodeJS SDK). For more details on how networkless verification works, refer to our Session Tokens documentation.

SecuritybearerAuth
Request
path Parameters
session_id
required
string

The ID of the session

Request Body schema: application/json

Parameters.

token
string

The JWT that is sent via the __session cookie from your frontend. Note: this JWT must be associated with the supplied session ID.

Responses
200

Success

400

Request was not successful

401

Authentication invalid

404

Resource not found

410

The endpoint is considered deprecated and is pending removal.

post/sessions/{session_id}/verify
Request samples
application/json
{
  • "token": "string"
}
Response samples
application/json
{
  • "object": "session",
  • "id": "string",
  • "user_id": "string",
  • "client_id": "string",
  • "actor": { },
  • "status": "active",
  • "last_active_organization_id": "string",
  • "last_active_at": 0,
  • "latest_activity": {
    },
  • "expire_at": 0,
  • "abandon_at": 0,
  • "updated_at": 0,
  • "created_at": 0
}

Create a session token

Creates a session JSON Web Token (JWT) based on a session.

SecuritybearerAuth
Request
path Parameters
session_id
required
string

The ID of the session

Request Body schema: application/json
expires_in_seconds
number or null [ 30 .. 315360000 ]

Use this parameter to override the default session token lifetime.

Responses
200

OK

401

Authentication invalid

404

Resource not found

post/sessions/{session_id}/tokens
Request samples
application/json
{
  • "expires_in_seconds": 30
}
Response samples
application/json
{
  • "object": "token",
  • "jwt": "string"
}

Create a session token from a jwt template

Creates a JSON Web Token(JWT) based on a session and a JWT Template name defined for your instance

SecuritybearerAuth
Request
path Parameters
session_id
required
string

The ID of the session

template_name
required
string

The name of the JWT Template defined in your instance (e.g. custom_hasura).

Request Body schema: application/json
expires_in_seconds
number or null [ 30 .. 315360000 ]

Use this parameter to override the JWT token lifetime.

Responses
200

OK

401

Authentication invalid

404

Resource not found

post/sessions/{session_id}/tokens/{template_name}
Request samples
application/json
{
  • "expires_in_seconds": 30
}
Response samples
application/json
{
  • "object": "token",
  • "jwt": "string"
}
➔ Next to Sign-in Tokens