Session object is an abstraction over an HTTP session. It models the period of information exchange between a user and the server.
Session object includes methods for recording session activity and ending the session client-side. For security reasons, sessions can also expire server-side.
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.
|A unique identifier for the session.|
|The user associated with the session.|
|Public information about the user that this session belongs to.|
|The current state of the session.|
|The time the session was last active on the |
|The time when the session was abandoned by the user.|
|The time the session expires and will seize to be active.|
|The last time the session recorded activity of any kind.|
|The time the session was created.|
|The last active token for the session|
|The last active organization identifier|
|The JWT actor for the session|
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.
|The session that was just ended.|
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.
|The session that was just removed.|
function touch(): Promise<Session>;
Touches the session, signifying some kind of user activity. Use this method to record any updates to user activity.
|The session that was just touched.|
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.
|The number of seconds to allow the token to be cached for.|
|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.
|Whether to throw an error or return an empty string, if an error occurs.|
|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).|
|The requested token.|
|The user's first name. This attribute will only be populated if name is enabled in instance settings.|
|The user's last name. This attribute will only be populated if name is enabled in instance settings.|
|A getter boolean to check if the user has uploaded an image or one was copied from OAuth. Returns |
|Whether the user has a profile image.|
|The user's identifier (email address, phone number, username, etc) that was used for authentication when this session was created.|
type SessionStatus = "abandoned" | "active" | "ended" | "expired" | "removed" | "replaced" | "revoked";
|The session was abandoned client-side.|
|The session is valid and all activity is allowed.|
|The user signed out of the session, but the |
|The period of allowed activity for this session has passed.|
|The user signed out of the session and the |
|The session has been replaced by another one, but the |
|The application ended the session and the |
Last updated on October 24, 2023