Skip to content

Commit 60d5742

Browse files
wangsijiewangsijie
authored
docs: add prebuilt Account Center UI documentation (#1354)
Add documentation for Logto's prebuilt Account Center UI feature.
1 parent 345cc77 commit 60d5742

File tree

2 files changed

+193
-15
lines changed

2 files changed

+193
-15
lines changed

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

Lines changed: 41 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,52 @@ import GearIcon from '@site/src/assets/gear.svg';
88

99
# Account settings
1010

11-
Logto provides a two collection of account settings APIs to allow users to manage their account and profiles stored in Logto.
11+
Logto provides multiple ways to let users manage their account and profiles stored in Logto.
1212

13-
## Use Account APIs (Recommended) \{#use-account-apis-recommended}
13+
## Use prebuilt Account Center UI (Recommended) \{#use-prebuilt-account-center-ui-recommended}
1414

15-
Logto’s Account APIs are ready-to-use, front-end endpoints that let end users securely view and update their own information with built-in permission checks. Simply embed them in your client application to power a polished, self-service account settings page.
15+
Logto provides a prebuilt Account Center UI that offers ready-to-use pages for end users to manage their account settings. This is the fastest way to add account management to your application.
16+
17+
Key features:
18+
19+
- **Zero development effort**: Ready-to-use pages that work out of the box.
20+
- **Consistent experience**: Matches the look and feel of Logto's sign-in experience.
21+
- **Security built-in**: All verification flows and security measures are handled automatically.
22+
- **Full functionality**: Supports updating email, phone, username, password, and MFA settings.
23+
24+
<DocCardList
25+
items={[
26+
{
27+
type: 'link',
28+
label: 'Use prebuilt Account Center UI (Recommended)',
29+
href: '/end-user-flows/account-settings/by-account-center-ui',
30+
description: 'Learn how to integrate Logto prebuilt Account Center UI into your application.',
31+
customProps: {
32+
icon: <GearIcon />,
33+
},
34+
},
35+
]}
36+
/>
37+
38+
## Use Account APIs \{#use-account-apis}
39+
40+
Logto's Account APIs are ready-to-use, front-end endpoints that let end users securely view and update their own information with built-in permission checks. Use this when you need to build a custom account settings page with your own UI.
1641

1742
Key features:
1843

1944
- **End-user settings**: Users manage their own sign-in identifiers and credentials, social accounts, MFA methods, and profile data.
2045
- **Client-side integration**: Designed for safe, direct use in your front-end.
21-
- **Minimal setup**: Turnkey endpoints without custom server required.
46+
- **Full customization**: Build your own UI while leveraging Logto's secure APIs.
2247
- **Permission control**: Toggle which Account APIs are enabled via Management API settings.
2348

2449
<DocCardList
2550
items={[
2651
{
2752
type: 'link',
28-
label: 'Use Logto Account APIs (Recommended)',
53+
label: 'Use Logto Account APIs',
2954
href: '/end-user-flows/account-settings/by-account-api',
3055
description:
31-
'Learn more about how to use the user Account APIs to build your own account settings page.',
56+
'Learn how to use the Account APIs to build your own custom account settings page.',
3257
customProps: {
3358
icon: <GearIcon />,
3459
},
@@ -61,13 +86,14 @@ Key features:
6186
]}
6287
/>
6388

64-
## Account API vs. Management API \{#account-api-vs-management-api}
89+
## Comparison of account settings options \{#comparison-of-account-settings-options}
6590

66-
| Feature | Account APIs | Management APIs |
67-
| ---------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
68-
| **Intended user** | End users | Admins / Developers |
69-
| **Access context** | Client-side / front-end | Server-side / back-end |
70-
| **Permission model** | Toggle which Account APIs are enabled via Management API. | Fully customizable by developers |
71-
| **Supported features** | 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. |
72-
| **Setup complexity** | Very low (plug-and-play) | Medium to high (requires custom implementation) |
73-
| **When to use** | To quick launch a secure, self-service account settings page in your client app with minimal setup. | 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 | 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 |

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

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
description: Learn how to use Logto's prebuilt Account Center UI to let users manage their accounts
3+
sidebar_position: 2
4+
---
5+
6+
# Account settings by prebuilt Account Center UI
7+
8+
## What is the prebuilt Account Center UI \{#what-is-the-prebuilt-account-center-ui}
9+
10+
Logto provides a prebuilt Account Center UI that offers ready-to-use pages for end users to manage their account settings. This prebuilt UI is hosted by Logto and handles common account management tasks including:
11+
12+
- Updating email address
13+
- Updating phone number
14+
- Updating username
15+
- Setting or updating password
16+
- Managing MFA settings (TOTP authenticator app, passkeys, backup codes)
17+
18+
The prebuilt Account Center UI is designed to work seamlessly with your application, providing a consistent user experience without requiring you to build custom account management pages.
19+
20+
## Benefits of using the prebuilt UI \{#benefits-of-using-the-prebuilt-ui}
21+
22+
- **Zero development effort**: Ready-to-use pages that work out of the box
23+
- **Consistent experience**: Matches the look and feel of Logto's sign-in experience
24+
- **Security built-in**: All verification flows and security measures are handled automatically
25+
- **Always up-to-date**: New features and security improvements are automatically available
26+
27+
## Available pages \{#available-pages}
28+
29+
The prebuilt Account Center UI provides the following pages, all accessible under the `/account` path of your Logto tenant endpoint:
30+
31+
| Path | Description |
32+
| -------------------------------- | --------------------------------- |
33+
| `/account/email` | Update primary email address |
34+
| `/account/phone` | Update primary phone number |
35+
| `/account/username` | Update username |
36+
| `/account/password` | Set or update password |
37+
| `/account/passkey/add` | Add a new passkey (WebAuthn) |
38+
| `/account/passkey/manage` | View and manage existing passkeys |
39+
| `/account/authenticator-app` | Set up TOTP authenticator app |
40+
| `/account/backup-codes/generate` | Generate new backup codes |
41+
| `/account/backup-codes/manage` | View and manage backup codes |
42+
43+
For example, if your tenant endpoint is `https://example.logto.app`, the email update page would be available at `https://example.logto.app/account/email`.
44+
45+
## How to use the prebuilt UI \{#how-to-use-the-prebuilt-ui}
46+
47+
### Step 1: Enable Account API \{#step-1-enable-account-api}
48+
49+
The prebuilt Account Center UI relies on the Account API. Navigate to <CloudLink to="/sign-in-experience/account-center">Console > Sign-in & account > Account center</CloudLink> and enable the Account API.
50+
51+
Configure the field permissions according to your needs:
52+
53+
- Set fields to `Edit` to allow users to modify them
54+
- Set fields to `ReadOnly` if users should only view them
55+
- Set fields to `Off` to hide them completely
56+
57+
### Step 2: Link to prebuilt pages from your application \{#step-2-link-to-prebuilt-pages}
58+
59+
To use the prebuilt Account Center UI, you need to redirect users from your application to the appropriate Logto pages. There are two approaches:
60+
61+
#### Approach A: Direct linking with redirect parameter \{#approach-a-direct-linking}
62+
63+
Add links in your application that redirect users to the prebuilt pages. Include a `redirect` query parameter to bring users back to your app after they complete the action:
64+
65+
```
66+
https://[tenant-id].logto.app/account/email?redirect=https://your-app.com/settings
67+
```
68+
69+
When users complete updating their email, they will be redirected back to `https://your-app.com/settings`.
70+
71+
#### Approach B: Embedding in your account settings flow \{#approach-b-embedding}
72+
73+
You can integrate the prebuilt pages into your existing account settings workflow:
74+
75+
1. In your app's account settings page, show the user's current information
76+
2. Provide "Edit" or "Update" buttons that link to the corresponding prebuilt pages
77+
3. After the user completes the action, they are redirected back to your app
78+
79+
Example implementation:
80+
81+
```tsx
82+
function AccountSettings() {
83+
const tenantEndpoint = 'https://example.logto.app';
84+
const redirectUrl = encodeURIComponent(window.location.href);
85+
86+
return (
87+
<div>
88+
<h2>Account Settings</h2>
89+
90+
<div>
91+
<span>Email: user@example.com</span>
92+
<a href={`${tenantEndpoint}/account/email?redirect=${redirectUrl}`}>Update Email</a>
93+
</div>
94+
95+
<div>
96+
<span>Password: ••••••••</span>
97+
<a href={`${tenantEndpoint}/account/password?redirect=${redirectUrl}`}>Change Password</a>
98+
</div>
99+
100+
<div>
101+
<span>MFA: Not configured</span>
102+
<a href={`${tenantEndpoint}/account/authenticator-app?redirect=${redirectUrl}`}>
103+
Set up Authenticator
104+
</a>
105+
</div>
106+
</div>
107+
);
108+
}
109+
```
110+
111+
### Step 3: Handle success redirects \{#step-3-handle-success-redirects}
112+
113+
After users complete an action, they will be redirected to your specified URL with an optional `show_success` query parameter. You can use this to display a success message:
114+
115+
```tsx
116+
function SettingsPage() {
117+
const searchParams = new URLSearchParams(window.location.search);
118+
const showSuccess = searchParams.get('show_success');
119+
120+
return (
121+
<div>
122+
{showSuccess === 'email' && <div>Email updated successfully!</div>}
123+
{showSuccess === 'password' && <div>Password updated successfully!</div>}
124+
{/* ... rest of your settings page */}
125+
</div>
126+
);
127+
}
128+
```
129+
130+
## Security considerations \{#security-considerations}
131+
132+
The prebuilt Account Center UI includes built-in security measures:
133+
134+
- **Identity verification**: Before making sensitive changes (email, phone, password, MFA), users must verify their identity using their current password or existing verification method
135+
- **Verification codes**: Email and phone updates require verification codes sent to the new address/number
136+
- **Session validation**: All operations validate the user's session to prevent unauthorized access
137+
138+
## Customization options \{#customization-options}
139+
140+
The prebuilt Account Center UI inherits the branding from your sign-in experience settings, including:
141+
142+
- Logo and colors
143+
- Dark/light mode
144+
- Language settings
145+
146+
If you need more customization beyond what the prebuilt UI offers, consider using the [Account API](/end-user-flows/account-settings/by-account-api) to build your own custom account management pages.
147+
148+
## Related resources \{#related-resources}
149+
150+
- [Account settings by Account API](/end-user-flows/account-settings/by-account-api) - Build custom account management with full API control
151+
- [Account settings by Management API](/end-user-flows/account-settings/by-management-api) - Admin-level account management
152+
- [MFA configuration](/end-user-flows/mfa) - Set up multi-factor authentication

0 commit comments

Comments
 (0)