Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerkstage.dev

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 mutli-session applications.

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

For more details regarding the different session states, see our documentation on session management.

Properties

NameTypeDescription
idstringA 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 time the session was created.
lastActiveTokenTokenResource | nullThe last active token for the session
lastActiveOrganizationIdstring | nullThe last active organization identifier
actorActJWTClaim | nullThe JWT actor for the session

Methods

end()

function end(): Promise<Session>;

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

Returns

TypeDescription
Promise<Session>The session that was just ended.

remove()

function remove(): Promise<Session>;

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

Returns

TypeDescription
Promise<Session>The session that was just removed.

touch()

function touch(): Promise<Session>;

Touches the session, signifying some kind of user activity. Use this method to record any updates to user activity.

Returns

TypeDescription
Promise<Session>The session that was just touched.

getToken()

function getToken(options?: GetTokenOptions): Promise<string | null>;

Retrieves the user's session token for the given template or the default clerk token. This method uses a cache so a network request will only be made if the token in memory has expired. The TTL for clerk token is one minute.

GetTokenOptions

NameTypeDescription
leewayInSecondsnumberThe number of seconds to allow the token to be cached for.
template?stringThe name of the JWT template from the Clerk Dashboard(opens in a new tab) 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.

Returns

TypeDescription
Promise<string | null>The requested token.

checkAuthorization()

function checkAuthorization(param: CheckAuthorizationParams) => boolean;

CheckAuthorizationParams

type CheckAuthorizationParams = | { role: ClerkDefaultRole | CustomRole; permission?: never; } | { role?: never; permission: ClerkDefaultPermission | CustomPermission; };
NameTypeDescription
rolestringAccepts role key
permissionstringAccepts permission key

Returns

TypeDescription
booleanA boolean that indicates if a user is authorized for the specified role or permission.

Types

PublicUserData

NameTypeDescription
firstNamestring | nullThe user's first name. This attribute will only be populated if name is enabled in instance settings.
lastNamestring | nullThe user's last name. This attribute will only be populated if name is enabled in instance settings.
imageUrlstringA getter boolean to check if the user has uploaded an image or one was copied from OAuth. Returns false if Clerk is displaying an avatar for the user.
hasImagebooleanWhether the user has a profile image.
identifierstringThe user's identifier (email address, phone number, username, etc) that was used for authentication when this session was created.

SessionStatus

type SessionStatus = "abandoned" | "active" | "ended" | "expired" | "removed" | "replaced" | "revoked";
ValueDescription
abandonedThe session was abandoned client-side.
activeThe session is valid and all activity is allowed.
endedThe user signed out of the session, but the Session remains in the Client object.
expiredThe period of allowed activity for this session has passed.
removedThe user signed out of the session and the Session was removed from the Client object.
replacedThe session has been replaced by another one, but the Session remains in the Client object.
revokedThe application ended the session and the Session was removed from the Client object.

What did you think of this content?

Clerk © 2024