Skip to content

docs: add session management flow #1377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
simeng-li merged 4 commits into from
Mar 18, 2026
Merged

docs: add session management flow #1377

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f7a7913
docs: update sign-out page
simeng-li Mar 6, 2026
a40f30b
docs: add session management flow
simeng-li Mar 6, 2026
49d2c0c
fix: fix anchors
simeng-li Mar 6, 2026
a20e6b6
docs: add recommended option comment
simeng-li Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/developers/signing-keys.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebar_position: 5

# Signing keys

Logto [OIDC signing keys](https://auth.wiki/signing-key), as known as "OIDC private keys" and "OIDC cookie keys", are the signing keys used to sign JWTs ([access tokens](https://auth.wiki/access-token) and [ID tokens](https://auth.wiki/id-token)) and browser cookies in Logto [sign-in sessions](/end-user-flows/sign-out#sign-in-session). These signing keys are generated when seeding Logto database ([open-source](/logto-oss)) or creating a new tenant ([Cloud](/logto-cloud)) and can be managed through [CLI](/logto-oss/using-cli) (open-source), Management APIs or Console UI.
Logto [OIDC signing keys](https://auth.wiki/signing-key), as known as "OIDC private keys" and "OIDC cookie keys", are the signing keys used to sign JWTs ([access tokens](https://auth.wiki/access-token) and [ID tokens](https://auth.wiki/id-token)) and browser cookies in Logto [sign-in sessions](/end-user-flows/sign-out#what-is-a-logto-session). These signing keys are generated when seeding Logto database ([open-source](/logto-oss)) or creating a new tenant ([Cloud](/logto-cloud)) and can be managed through [CLI](/logto-oss/using-cli) (open-source), Management APIs or Console UI.

By default, Logto uses the elliptic curve (EC) algorithm to generate digital signatures. However, considering that users often need to verify JWT signatures and many older tools do not support the EC algorithm (only supporting RSA), we have implemented the functionality to rotate private keys and allow users to choose the signature algorithm (including both RSA and EC). This ensures compatibility with services that use outdated signature verification tools.

Expand Down
2 changes: 1 addition & 1 deletion docs/end-user-flows/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ End-user flows cover all verification processes for user interactions, categoriz
| [Magic link (One-time token)](/end-user-flows/one-time-token) | <ul><li>Organization member invitation</li><li>User invitation when registration is disabled</li><li>Sign in or sign up using magic link</li></ul> |
| Authorize third-party apps | <ul><li>[Consent screen for OIDC / OAuth apps](/end-user-flows/consent-screen)</li></ul> |
| Collect user profile | <ul><li>[Collect additional user data during sign-up](/end-user-flows/collect-user-profile)</li></ul> |
| [Sign-out](/end-user-flows/sign-out) | <ul><li>[Clear tokens and local session at the client side](/end-user-flows/sign-out/#clear-tokens-and-local-session-at-the-client-side)</li><li>[Clear sign-in session at Logto](/end-user-flows/sign-out/#clear-sign-in-session-at-logto)</li><li>[Federated sign-out: Back-channel logout](/end-user-flows/sign-out/#federated-sign-out-back-channel-logout)</li></ul> |
| [Sign-out](/end-user-flows/sign-out) | <ul><li>[Clear tokens and local session at the client side](/end-user-flows/sign-out/#1-client-side-only-sign-out)</li><li>[Clear sign-in session at Logto](/end-user-flows/sign-out/#2-end-session-at-logto-global-sign-out-in-current-logto-implementation)</li><li>[Federated sign-out: Back-channel logout](/end-user-flows/sign-out/#federated-sign-out-back-channel-logout)</li></ul> |

This section introduces Logto’s pre-built UI for a streamlined sign-in experience, helping you accelerate time-to-market. For more flexibility in customizing your sign-in UI, try the “[Bring Your UI](/customization/bring-your-ui)” feature with Logto Experience APIs.

Expand Down
20 changes: 10 additions & 10 deletions docs/end-user-flows/account-settings/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Logto's Account APIs are ready-to-use, front-end endpoints that let end users se

Key features:

- **End-user settings**: Users manage their own sign-in identifiers and credentials, social accounts, MFA methods, and profile data.
- **End-user settings**: Users manage their own sign-in identifiers and credentials, social accounts, MFA methods, profile data and sessions.
- **Client-side integration**: Designed for safe, direct use in your front-end.
- **Full customization**: Build your own UI while leveraging Logto's secure APIs.
- **Permission control**: Toggle which Account APIs are enabled via Management API settings.
Expand Down Expand Up @@ -88,12 +88,12 @@ Key features:

## Comparison of account settings options \{#comparison-of-account-settings-options}

| Feature | Prebuilt Account Center UI | Account APIs | Management APIs |
| ---------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Intended user** | End users | End users | Admins / Developers |
| **Access context** | Redirect to Logto-hosted pages | Client-side / front-end | Server-side / back-end |
| **Permission model** | Toggle which fields are enabled via Account center settings | Toggle which Account APIs are enabled via Management API | Fully customizable by developers |
| **Supported features** | Update: email, phone, username, password, MFA (TOTP, passkeys, backup codes) | View, update, and delete: username, email, phone, password, social accounts, MFA, profile | All basic settings + Delete/suspend/restore account, Personal access tokens, user impersonation, connect OAuth apps, etc. |
| **UI customization** | Inherits sign-in experience branding | Full customization (build your own UI) | Full customization (build your own UI) |
| **Setup complexity** | None (just link to prebuilt pages) | Low (use APIs with your UI) | Medium to high (requires custom implementation) |
| **When to use** | For the fastest way to add account management without building custom pages | When you need custom UI but want to leverage Logto's secure APIs | When Account APIs don't meet your needs. E.g., for complex account deletion logic, high-risk actions, or building back-office tools |
| Feature | Prebuilt Account Center UI | Account APIs | Management APIs |
| ---------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Intended user** | End users | End users | Admins / Developers |
| **Access context** | Redirect to Logto-hosted pages | Client-side / front-end | Server-side / back-end |
| **Permission model** | Toggle which fields are enabled via Account center settings | Toggle which Account APIs are enabled via Management API | Fully customizable by developers |
| **Supported features** | Update: email, phone, username, password, MFA (TOTP, passkeys, backup codes) | View, update, and delete: username, email, phone, password, social accounts, MFA, profile, sessions | All basic settings + Delete/suspend/restore account, Personal access tokens, user impersonation, connect OAuth apps, session, etc. |
| **UI customization** | Inherits sign-in experience branding | Full customization (build your own UI) | Full customization (build your own UI) |
| **Setup complexity** | None (just link to prebuilt pages) | Low (use APIs with your UI) | Medium to high (requires custom implementation) |
| **When to use** | For the fastest way to add account management without building custom pages | When you need custom UI but want to leverage Logto's secure APIs | When Account APIs don't meet your needs. E.g., for complex account deletion logic, high-risk actions, or building back-office tools |
52 changes: 51 additions & 1 deletion docs/end-user-flows/account-settings/by-account-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ Some frequent use cases are listed below:
- Update user password
- Update user identities including email, phone, and social connections
- Manage MFA factors (verifications)
- Manage user sessions

To learn more about the available APIs, please visit [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) and [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications).

Expand All @@ -47,7 +48,11 @@ Once enabled, configure per-field permissions for identifiers, profile data, and
2. **Profile fields**:
- Fields include: username, name, avatar, [profile](/user-management/user-data#profile) (other standard profile attributes), and [custom data](/user-management/user-data#custom-data).
- End users can edit these without additional verification.
3. **Secret vault**: For OIDC or OAuth social and enterprise connectors, Logto [secret vault](/secret-vault/federated-token-set) securely stores third-party access and refresh tokens after authentication. Apps can then call external APIs, such as syncing Google Calendar events, without prompting users to sign in again. Token retrieval becomes available automatically once the Account API is enabled.
3. **Secret vault**:
- For OIDC or OAuth social and enterprise connectors, Logto [secret vault](/secret-vault/federated-token-set) securely stores third-party access and refresh tokens after authentication. Apps can then call external APIs, such as syncing Google Calendar events, without prompting users to sign in again. Token retrieval becomes available automatically once the Account API is enabled.
4. **Session management**:
- When enabled, users can view and manage their active sessions, including device information and last sign-in time. Users can also revoke sessions to log out from specific devices.
- Before end users access session management, they must verify their identity via password, email, or SMS to obtain a 10-minute verification record ID. See [Get a verification record id](#get-a-verification-record-id).

## How to access Account API \{#how-to-access-account-api}

Expand All @@ -69,6 +74,7 @@ const config: LogtoConfig = {
UserScope.Address, // To manage address
UserScope.Identities, // For identity and MFA related APIs
UserScope.Profile, // To manage user profile
UserScope.Sessions, // To manage user sessions
],
};
```
Expand Down Expand Up @@ -663,3 +669,47 @@ The response body would be like:

- `code`: the backup code.
- `usedAt`: the timestamp when the code was used, `null` if not used yet.

### Manage user sessions \{#manage-user-sessions}

**List active sessions**

To list the user's active sessions, you can use the [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) endpoint.

:::note

- `UserScope.Sessions` scope is required to access this endpoint.
- `Sessions` field in account center settings must be set to `ReadOnly` or `Edit`.

:::

```bash
curl https://[tenant-id].logto.app/api/my-account/sessions \
-H 'authorization: Bearer <access_token>' \
-H 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json'
```

**Revoke session by session ID**

To revoke a specific session, use the [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) endpoint.

:::note

- `UserScope.Sessions` scope is required to access this endpoint.
- `Sessions` field in account center settings must be set to `Edit`.
:::

```bash
curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
-H 'authorization: Bearer <access_token>' \
-H 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json'
```

Optional query parameters:

- `revokeGrantsTarget`: Optionally specify the target of the grants to revoke along with the session. Possible values:
- `all`: Revoke all grants associated with the session
- `firstParty`: Revoke only first-party app grants associated with the session
- unspecified: Default behavior revokes grants that does not have `offline_access` scope, which typically means revoking non-refresh-token grants for the session.
8 changes: 8 additions & 0 deletions docs/end-user-flows/account-settings/by-management-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,3 +194,11 @@ Personal access tokens provide a secure way for users to grant [access token](ht
| method | path | description |
| ------ | -------------------------------------------------------------------------------- | ------------------------- |
| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Delete a user by user ID. |

### User session management \{#user-session-management}

| method | path | description |
| ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Get user sessions by user ID. |
| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Get a user session by session ID. |
| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Delete a user session by session ID. |
Loading
Loading