āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/reference/javascript/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.
[!NOTE] For more information regarding the different session states, see the guide on session management.
The unique identifier for the session.
userUserThe user associated with the session.
publicUserDataPublicUserDataPublic information about the user that this session belongs to.
statusSessionStatusThe current state of the session.
lastActiveAtDateThe time the session was last active on the Client.
abandonAtDateThe time when the session was abandoned by the user.
expireAtDateThe time the session expires and will cease to be active.
updatedAtDateThe last time the session recorded activity of any kind.
createdAtDateThe date when the session was created.
lastActiveTokenTokenResource | nullThe last active token for the session
lastActiveOrganizationIdstring | nullThe ID of the last active organization.
factorVerificationAge[number, number] | nullAn array where each item represents the number of minutes since the last verification of a first or second factor: [firstFactorAge, secondFactorAge].
actorActJWTClaim | nullThe JWT actor for the session. Holds identifier for the user that is impersonating the current user. Read more about impersonation.
currentTaskThe current pending task for the session. Read more about session tasks. </Properties>
attemptFirstFactorVerification()Attempts to complete the first factor verification process. Returns a SessionVerification instance with its status and supported factors.
function attemptFirstFactorVerification(
params: SessionVerifyAttemptFirstFactorParams,
): Promise<SessionVerificationResource>
SessionVerifyAttemptFirstFactorParamstype SessionVerifyAttemptFirstFactorParams = EmailCodeAttempt | PhoneCodeAttempt | PasswordAttempt
type EmailCodeAttempt = {
strategy: 'email_code'
code: string
}
type PhoneCodeAttempt = {
strategy: 'phone_code'
code: string
}
type PasswordAttempt = {
strategy: 'password'
password: string
}
await clerk.session.attemptFirstFactorVerification({
strategy: 'email_code',
code: '123456',
})
attemptSecondFactorVerification()Attempts to complete the second factor verification process. Returns a SessionVerification instance with its status and supported factors.
function attemptSecondFactorVerification(
params: SessionVerifyAttemptSecondFactorParams,
): Promise<SessionVerificationResource>
SessionVerifyAttemptSecondFactorParamstype SessionVerifyAttemptSecondFactorParams = PhoneCodeAttempt | TOTPAttempt | BackupCodeAttempt
type PhoneCodeAttempt = {
strategy: 'phone_code'
code: string
}
type TOTPAttempt = {
strategy: 'totp'
code: string
}
type BackupCodeAttempt = {
strategy: 'backup_code'
code: string
}
await clerk.session.attemptSecondFactorVerification({
strategy: 'phone_code',
code: '123456',
})
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(param: CheckAuthorizationParams): boolean
CheckAuthorizationParamstype WithReverification<T> = T & {
/**
* The reverification configuration to check for. This feature is currently in public beta. **It is not recommended for production use.**
*/
reverification?: ReverificationConfig
}
type CheckAuthorizationParams = WithReverification<
| {
/**
* The [role](https://clerk.com/docs/guides/organizations/roles-and-permissions) to check for.
*/
role: OrganizationCustomRoleKey
/**
* The [permission](https://clerk.com/docs/guides/organizations/roles-and-permissions) to check for.
*/
permission?: never
/**
* The [feature](https://clerk.com/docs/guides/billing/overview) to check for.
*/
feature?: never
/**
* The [plan](https://clerk.com/docs/guides/billing/overview) to check for.
*/
plan?: never
}
| {
role?: never
permission: OrganizationPermissionKey
feature?: never
plan?: never
}
| {
role?: never
permission?: never
feature: Autocomplete<`user:${string}` | `org:${string}`>
plan?: never
}
| {
role?: never
permission?: never
feature?: never
plan: Autocomplete<`user:${string}` | `org:${string}`>
}
| { role?: never; permission?: never; feature?: never; plan?: never }
>
Accepts role key.
permissionstringAccepts permission key.
featurestringAccepts feature key.
planstringAccepts plan key.
reverification?The reverification configuration to check for. This feature is currently in public beta. It is not recommended for production use. </Properties>
For more information, see the guide on authorization checks.
// Check if the current user has the 'admin' role
await clerk.session.checkAuthorization({
role: 'admin',
})
For more information, see the guide on reverification.
// Require the user to reverify their first factor after 2 minutes
await clerk.session.checkAuthorization({
reverification: { afterMinutes: 2, level: 'first_factor' },
})
end()Terminates the current session, invalidating it for this Client instance. Upon completion, the session's status transitions to ended and all associated authentication tokens are revoked. This operation cannot be undone and requires re-authentication to establish a new session.
function end(): Promise<Session>
await clerk.session.end()
getToken()Retrieves the current user's session token or a custom JWT 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.
function getToken(options?: GetTokenOptions): Promise<string | null>
GetTokenOptionsThe number of seconds to allow the token to be cached for.
template?stringThe 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.
throwOnError?booleanWhether to throw an error or return an empty string, if an error occurs.
skipCache?booleanWhether 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 to false.
organizationId?stringThe organization associated with the generated session token. Does not modify the session's currently active organization. </Properties>
await clerk.session.getToken({ template: 'Test' })
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.
function prepareFirstFactorVerification(
params: SessionVerifyPrepareFirstFactorParams,
): Promise<SessionVerificationResource>
SessionVerifyPrepareFirstFactorParamstype SessionVerifyPrepareFirstFactorParams = EmailCodeConfig | PhoneCodeConfig
type EmailCodeConfig = {
strategy: 'email_code'
primary?: boolean | undefined
emailAddressId: string
}
type PhoneCodeConfig = {
strategy: 'phone_code'
phoneNumberId: string
primary?: boolean
default?: boolean
}
await clerk.session.prepareFirstFactorVerification({
strategy: 'email_code',
emailAddressId: 'email_address_123',
})
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.
function prepareSecondFactorVerification(
params: SessionVerifyPrepareSecondFactorParams,
): Promise<SessionVerificationResource>
SessionVerifyPrepareSecondFactorParamstype SessionVerifyPrepareSecondFactorParams = PhoneCodeSecondFactorConfig
type PhoneCodeSecondFactorConfig = {
strategy: 'phone_code'
phoneNumberId?: string
}
await clerk.session.prepareSecondFactorVerification({
strategy: 'phone_code',
})
remove()Invalidates the current session by marking it as removed. Once removed, the session will be deactivated for the current Client instance and its status will be set to removed. This operation cannot be undone.
function remove(): Promise<Session>
await clerk.session.remove()
startVerification()Initiates the reverification flow. Returns a SessionVerification instance with its status and supported factors.
function startVerification(params: SessionVerifyCreateParams): Promise<SessionVerificationResource>
SessionVerifyCreateParamstype SessionVerifyCreateParams = {
level: 'first_factor' | 'second_factor' | 'multi_factor'
}
await clerk.session.startVerification({
level: 'first_factor',
})
touch()Updates the session's last active timestamp to the current time. This method should be called periodically to indicate ongoing user activity and prevent the session from becoming stale. The updated timestamp is used for session management and analytics purposes.
function touch(): Promise<Session>
await clerk.session.touch()
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā