Session object

The Session object is an abstraction over an HTTP session. It models the period of information exchange between a user and the server.

The Session object includes methods for recording session activity and ending the session client-side. For security reasons, sessions can also expire server-side.

As soon as a User signs in, Clerk creates a Session for the current Client. Clients can have more than one session at any point in time, but only one of those sessions will be active.

In certain scenarios, a session might be replaced by another one. This is often the case with multi-session applications.

All sessions that are expired, removed, replaced, ended or abandoned are not considered valid.

Note

For more information regarding the different session states, see the guide on session management.

Example

The Session object is available on the Clerk object.

Example Code

import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)

// Load Clerk
await clerk.load()

// Access the session object
const session = clerk.session

Properties

• Name abandonAt Type Date Description The date and time when the session was abandoned by the user.
• Name actor Type null | { [x: string]: unknown; sub: string; type?: "agent"; } Description The JWT actor for the session. Holds identifier for the user that is impersonating the current user. Read more about impersonation.
• Name actor.sub Type string Description The identifier for the user that is impersonating the current user.
• Name actor.type? Type "agent" Description The type of the actor.
• Name agent Type null | { [x: string]: unknown; sub: string; type?: "agent"; } & { type: "agent"; } Description When the session's actor claim has type: 'agent', this property exposes information about the agent and Agent Task that was used to create the session.
• Name createdAt Type Date Description The date and time when the session was first created.
• Name expireAt Type Date Description The date and time when the session will expire.
• Name id Type string Description The unique identifier for the session.
• Name lastActiveAt Type Date Description The date and time when the session was last active on the Client.
• Name status Type SessionStatus Description The current state of the session.

Methods

attemptFirstFactorVerification()

Attempts to complete the first factor verification⁠ process.

Returns a SessionVerification instance with its status and supported factors.

function attemptFirstFactorVerification(attemptFactor: SessionVerifyAttemptFirstFactorParams): Promise<SessionVerificationResource>

checkAuthorization()

Checks if the user is authorized for the specified Role, Permission, Feature, or Plan or requires the user to reverify their credentials if their last verification is older than allowed.

function checkAuthorization(isAuthorizedParams: CheckAuthorizationParams): boolean

clearCache()

Clears the cache for the current session. This is useful if the session has been updated and the cache is no longer valid.

function clearCache(): void

end()

Marks the session as ended. The session will no longer be active for this Client and its status will become ended.

function end(): Promise<SessionResource>

getToken()

Gets the current user's session token or a custom JWT template.

verifyWithPasskey()

Initiates a verification flow using passkeys.

Returns a SessionVerification instance with its status and supported factors.

function verifyWithPasskey(): Promise<SessionVerificationResource>

Feedback

What did you think of this content?

It's been marked as helpful and up to date.