Session
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 sessions 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.
- Name
id
- Type
string
- Description
The unique identifier for the session.
- Name
user
- Type
User
- Description
The user associated with the session.
- Name
publicUserData
- Type
PublicUserData
- Description
Public information about the user that this session belongs to.
- Name
status
- Type
SessionStatus
- Description
The current state of the session.
- Name
lastActiveAt
- Type
Date
- Description
The time the session was last active on the
Client
.
- Name
abandonAt
- Type
Date
- Description
The time when the session was abandoned by the user.
- Name
expireAt
- Type
Date
- Description
The time the session expires and will cease to be active.
- Name
updatedAt
- Type
Date
- Description
The last time the session recorded activity of any kind.
- Name
createdAt
- Type
Date
- Description
The date when the session was created.
- Name
lastActiveToken
- Type
TokenResource | null
- Description
The last active token for the session
- Name
lastActiveOrganizationId
- Type
string | null
- Description
The last active organization identifier
- Name
factorVerificationAge
- Type
[number, number] | null
- Description
An array where each item represents the number of minutes since the last verification of a first or second factor:
[firstFactorAge, secondFactorAge]
.
- Name
actor
- Type
ActJWTClaim | null
- Description
The JWT actor for the session
Methods
end()
Marks the session as ended. The session will no longer be active for this Client
and its status will become ended.
remove()
Marks the session as removed. The session will no longer be active for this Client and its status will become removed.
touch()
Touches the session, signifying some kind of user activity. Use this method to record any updates to user activity.
getToken()
Retrieves the user's session token for the default Clerk token or the given template.
This method uses a cache so a network request will only be made if the token in memory has expired. The TTL for a Clerk token is one minute.
Tokens can only be generated if the user is signed in.
- Name
leewayInSeconds
- Type
number
- Description
The number of seconds to allow the token to be cached for.
- Name
template?
- Type
string
- Description
The name of the JWT template from the Clerk Dashboard to generate a new token from.
E.g. 'firebase', 'grafbase', or your custom template's name.
- Name
throwOnError?
- Type
boolean
- Description
Whether to throw an error or return an empty string, if an error occurs.
- Name
skipCache?
- Type
boolean
- Description
Whether to skip the cache lookup and force a call to the server instead, even within the TTL. Useful if the token claims are time-sensitive or depend on data that can be updated (e.g. user fields).
Defaults tofalse
.
- Name
organizationId?
- Type
string
- Description
The organization associated with the generated session token. Does not modify the session's currently active organization.
checkAuthorization()
Checks if the user is authorized for the specified role or permission.
- Name
role
- Type
string
- Description
Accepts role key
- Name
permission
- Type
string
- Description
Accepts permission key
- Name
reverification?
- Type
ReverificationConfig
- Description
The reverification configuration to check for.
startVerification()
Initiates the reverification flow. Returns a SessionVerification
instance with its status and supported factors.
prepareFirstFactorVerification()
Initiates the first factor verification process. This is a required step to complete a reverification flow when using a preparable factor. Returns a SessionVerification
instance with its status and supported factors.
attemptFirstFactorVerification()
Attempts to complete the first factor verification process. Returns a SessionVerification
instance with its status and supported factors.
prepareSecondFactorVerification()
Initiates the second factor verification process. This is a required step to complete a reverification flow when using a preparable factor. Returns a SessionVerification
instance with its status and supported factors.
attemptSecondFactorVerification()
Attempts to complete the second factor verification process. Returns a SessionVerification
instance with its status and supported factors.
Feedback
Last updated on