SDKsTypeScript SDKAuthentication
Session Management
Get, list, and revoke user sessions with the TypeScript SDK.
Session Management
After authentication, the SDK manages user sessions. You can retrieve the current session, list all active sessions, and revoke sessions individually or in bulk.
getSession()
Retrieve the currently authenticated session.
getSession(params?: GetSessionParams): Promise<Session | null>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tokenize | string[] | no | Token templates to include in response |
Returns
Promise<Session | null> -- The current session, or null if not authenticated.
Basic usage
const session = await client.getSession();
if (session) {
console.log(session.id); // "ses_abc123..."
console.log(session.identity.id); // "usr_abc123..."
console.log(session.identity.email); // "[email protected]"
console.log(session.identity.name); // { first: "Jane", last: "Doe" }
console.log(session.expiresAt); // "2026-04-09T12:00:00Z"
console.log(session.authenticatedAt); // "2026-04-08T10:00:00Z"
console.log(session.authenticatorAssuranceLevel); // "aal1" | "aal2"
console.log(session.active); // true
console.log(session.devices); // [{ id: "dev_...", userAgent: "..." }]
} else {
console.log("Not authenticated");
redirectToLogin();
}Check authentication in a route guard
// React Router loader
export async function loader() {
const session = await client.getSession();
if (!session) {
throw redirect("/login");
}
return { session };
}Check session with MFA assurance level
const session = await client.getSession();
if (!session) {
redirectToLogin();
} else if (session.authenticatorAssuranceLevel === "aal1") {
// User is logged in but has not completed MFA.
// For sensitive operations, require AAL2.
redirectToMfaChallenge();
} else {
// AAL2 -- user has completed MFA
showSensitiveContent();
}listSessions()
List all active sessions for the current user. Useful for showing "Where you're logged in" in account settings.
listSessions(params?: ListSessionsParams): Promise<SessionList>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
pageSize | number | no | Sessions per page (default: 25, max: 100) |
pageToken | string | no | Pagination token from a previous response |
active | boolean | no | Filter by active status (default: true) |
Returns
Promise<SessionList> -- Paginated list of sessions.
interface SessionList {
sessions: Session[];
nextPageToken: string | null;
totalSize: number;
}Basic usage
const result = await client.listSessions({ pageSize: 10 });
for (const session of result.sessions) {
console.log(session.id);
console.log(session.devices[0]?.userAgent); // "Chrome 120 on macOS"
console.log(session.devices[0]?.ipAddress); // "203.0.113.42"
console.log(session.devices[0]?.location); // "San Francisco, CA, US"
console.log(session.authenticatedAt);
console.log(session.active);
}
// Paginate
if (result.nextPageToken) {
const nextPage = await client.listSessions({
pageSize: 10,
pageToken: result.nextPageToken,
});
}Display all sessions with current indicator
const currentSession = await client.getSession();
const allSessions = await client.listSessions();
for (const session of allSessions.sessions) {
const isCurrent = session.id === currentSession?.id;
console.log(`${session.id} ${isCurrent ? "(current)" : ""}`);
console.log(` Device: ${session.devices[0]?.userAgent}`);
console.log(` Location: ${session.devices[0]?.location}`);
console.log(` Last active: ${session.authenticatedAt}`);
}revokeSession()
Revoke a specific session by ID. The user will be logged out on that device.
revokeSession(params: RevokeSessionParams): Promise<void>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string | yes | ID of the session to revoke |
Basic usage
// Revoke a specific session (e.g., from "Where you're logged in" list)
await client.revokeSession({ sessionId: "ses_abc123" });
console.log("Session revoked.");Revoke all sessions except current
const currentSession = await client.getSession();
const allSessions = await client.listSessions();
for (const session of allSessions.sessions) {
if (session.id !== currentSession?.id) {
await client.revokeSession({ sessionId: session.id });
}
}
console.log("All other sessions revoked.");revokeAllSessions()
Revoke all sessions for the current user, including the current one. This is a "log out everywhere" operation.
revokeAllSessions(): Promise<void>Basic usage
await client.revokeAllSessions();
// User is now logged out on all devices
redirectToLogin();logout()
End the current session and clear local tokens.
logout(params?: LogoutParams): Promise<void>Parameters
| Name | Type | Required | Description |
|---|---|---|---|
everywhere | boolean | no | If true, revoke all sessions (default: false) |
Basic usage
// Log out of current session only
await client.logout();
redirectToLogin();
// Log out of all sessions everywhere
await client.logout({ everywhere: true });
redirectToLogin();Session properties
| Property | Type | Description |
|---|---|---|
id | string | Unique session identifier |
active | boolean | Whether the session is currently valid |
expiresAt | string | ISO 8601 expiry timestamp |
authenticatedAt | string | When the session was created |
authenticatorAssuranceLevel | "aal1" | "aal2" | MFA level achieved |
identity | Identity | The authenticated user's identity |
devices | DeviceInfo[] | Devices associated with this session |
authenticationMethods | AuthMethod[] | Methods used to authenticate |
Common errors
| Error class | HTTP status | When |
|---|---|---|
UnauthorizedError | 401 | No valid session / session expired |
NotFoundError | 404 | Session ID not found (already revoked) |
ForbiddenError | 403 | Cannot revoke another user's session |
RateLimitError | 429 | Too many requests |
See also
- Login -- Authenticate users
- MFA -- Multi-factor authentication
- Session type -- Full Session type definition
- React guide -- Session management in React apps