Skip to content

Commit 794b5d5

Browse files
simeng-lisimeng-li
authored
docs: add session management flow (#1377)
* docs: update sign-out page update sign-out page by adding new session management related topics * docs: add session management flow add session management flow to account APIs and management APIs * fix: fix anchors fix anchors * docs: add recommended option comment add recommented option comment
1 parent 4c4ab0e commit 794b5d5

File tree

8 files changed

+273
-167
lines changed

8 files changed

+273
-167
lines changed

‎docs/developers/signing-keys.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ sidebar_position: 5
77

88
# Signing keys
99

10-
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.
10+
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.
1111

1212
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.
1313

‎docs/end-user-flows/README.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ End-user flows cover all verification processes for user interactions, categoriz
2121
| [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> |
2222
| Authorize third-party apps | <ul><li>[Consent screen for OIDC / OAuth apps](/end-user-flows/consent-screen)</li></ul> |
2323
| Collect user profile | <ul><li>[Collect additional user data during sign-up](/end-user-flows/collect-user-profile)</li></ul> |
24-
| [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> |
24+
| [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> |
2525

2626
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.
2727

‎docs/end-user-flows/account-settings/README.mdx‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ Logto's Account APIs are ready-to-use, front-end endpoints that let end users se
4141

4242
Key features:
4343

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

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

91-
| Feature | Prebuilt Account Center UI | Account APIs | Management APIs |
92-
| ---------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
93-
| **Intended user** | End users | End users | Admins / Developers |
94-
| **Access context** | Redirect to Logto-hosted pages | Client-side / front-end | Server-side / back-end |
95-
| **Permission model** | Toggle which fields are enabled via Account center settings | Toggle which Account APIs are enabled via Management API | Fully customizable by developers |
96-
| **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. |
97-
| **UI customization** | Inherits sign-in experience branding | Full customization (build your own UI) | Full customization (build your own UI) |
98-
| **Setup complexity** | None (just link to prebuilt pages) | Low (use APIs with your UI) | Medium to high (requires custom implementation) |
99-
| **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 |
91+
| Feature | Prebuilt Account Center UI | Account APIs | Management APIs |
92+
| ---------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
93+
| **Intended user** | End users | End users | Admins / Developers |
94+
| **Access context** | Redirect to Logto-hosted pages | Client-side / front-end | Server-side / back-end |
95+
| **Permission model** | Toggle which fields are enabled via Account center settings | Toggle which Account APIs are enabled via Management API | Fully customizable by developers |
96+
| **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. |
97+
| **UI customization** | Inherits sign-in experience branding | Full customization (build your own UI) | Full customization (build your own UI) |
98+
| **Setup complexity** | None (just link to prebuilt pages) | Low (use APIs with your UI) | Medium to high (requires custom implementation) |
99+
| **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 |

‎docs/end-user-flows/account-settings/by-account-api.mdx‎

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Some frequent use cases are listed below:
2323
- Update user password
2424
- Update user identities including email, phone, and social connections
2525
- Manage MFA factors (verifications)
26+
- Manage user sessions
2627

2728
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).
2829

@@ -47,7 +48,11 @@ Once enabled, configure per-field permissions for identifiers, profile data, and
4748
2. **Profile fields**:
4849
- Fields include: username, name, avatar, [profile](/user-management/user-data#profile) (other standard profile attributes), and [custom data](/user-management/user-data#custom-data).
4950
- End users can edit these without additional verification.
50-
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.
51+
3. **Secret vault**:
52+
- 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.
53+
4. **Session management**:
54+
- 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.
55+
- 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).
5156

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

@@ -69,6 +74,7 @@ const config: LogtoConfig = {
6974
UserScope.Address, // To manage address
7075
UserScope.Identities, // For identity and MFA related APIs
7176
UserScope.Profile, // To manage user profile
77+
UserScope.Sessions, // To manage user sessions
7278
],
7379
};
7480
```
@@ -663,3 +669,47 @@ The response body would be like:
663669

664670
- `code`: the backup code.
665671
- `usedAt`: the timestamp when the code was used, `null` if not used yet.
672+
673+
### Manage user sessions \{#manage-user-sessions}
674+
675+
**List active sessions**
676+
677+
To list the user's active sessions, you can use the [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) endpoint.
678+
679+
:::note
680+
681+
- `UserScope.Sessions` scope is required to access this endpoint.
682+
- `Sessions` field in account center settings must be set to `ReadOnly` or `Edit`.
683+
684+
:::
685+
686+
```bash
687+
curl https://[tenant-id].logto.app/api/my-account/sessions \
688+
-H 'authorization: Bearer <access_token>' \
689+
-H 'logto-verification-id: <verification_record_id>' \
690+
-H 'content-type: application/json'
691+
```
692+
693+
**Revoke session by session ID**
694+
695+
To revoke a specific session, use the [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) endpoint.
696+
697+
:::note
698+
699+
- `UserScope.Sessions` scope is required to access this endpoint.
700+
- `Sessions` field in account center settings must be set to `Edit`.
701+
:::
702+
703+
```bash
704+
curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
705+
-H 'authorization: Bearer <access_token>' \
706+
-H 'logto-verification-id: <verification_record_id>' \
707+
-H 'content-type: application/json'
708+
```
709+
710+
Optional query parameters:
711+
712+
- `revokeGrantsTarget`: Optionally specify the target of the grants to revoke along with the session. Possible values:
713+
- `all`: Revoke all grants associated with the session.
714+
- `firstParty`: Revoke only first-party app grants associated with the session. (Recommended for most use cases, as it revokes access for your own app while keeping third-party app grants intact, providing a better user experience.)
715+
- unspecified: Default behavior revokes grants that does not have `offline_access` scope, which typically means revoking non-refresh-token grants for the session.

‎docs/end-user-flows/account-settings/by-management-api.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,3 +194,11 @@ Personal access tokens provide a secure way for users to grant [access token](ht
194194
| method | path | description |
195195
| ------ | -------------------------------------------------------------------------------- | ------------------------- |
196196
| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Delete a user by user ID. |
197+
198+
### User session management \{#user-session-management}
199+
200+
| method | path | description |
201+
| ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
202+
| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Get user sessions by user ID. |
203+
| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Get a user session by session ID. |
204+
| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Delete a user session by session ID. |

0 commit comments

Comments
 (0)