Account & sign-in security
3.8.1 adds a set of account security features for both members and admins:
| For | New features |
|---|---|
| Members | Two-step verification, fund operation verification, sign-in device management, security log, passkey sign-in |
| Admins | Passkey sign-in, idle lock screen, a new sign-in page |
3.8.2 adds the integration IP whitelist: once an account registers server IPs, the integration API only accepts balance orders from those servers — and accounts with fund operation verification on need it to place integration orders at all.
Upgrade notes
After upgrading to 3.8.1 you will notice the following — all of it is expected. For how to upgrade, see upgrading and migrating.
- Every member has to sign in once more. Member sign-in credentials were rebuilt for security, so existing member sessions end.
- Passwords are stored with a stronger hash. Member and admin passwords are converted automatically the next time each account signs in with its password; nothing for you to do. When an admin's password is converted, that admin's sessions on other devices end — just sign in again there.
- The admin idle lock screen is on by default, at 15 minutes — see "Idle lock screen" below. The upgrade itself does not sign admins out.
- Database changes are applied by the online upgrade. There is no SQL to run by hand.
Do not roll back to an older version after upgrading. Accounts whose passwords have been converted can no longer sign in with their password on an older version.
For members
The security navigation in the user centre — the row with Profile, Password, Email and Mobile — gains these pages:
| Page | What it is for |
|---|---|
| Two-step verification | Asks for a code from an authenticator app on top of the password at sign-in; the fund operation verification switch lives here too |
| Sign-in Devices | Shows which devices are signed in to the account, and signs them out |
| Integration whitelist | New in 3.8.2: the server IPs allowed to pay from the balance through the integration API. Only the default theme has this page; other themes show it on the Two-step verification page |
| Security log | A record of sign-ins, password changes, withdrawals and other important actions |
| Passkeys | Sign in with a fingerprint, face or device PIN instead of a password |
Two-step verification
To turn it on:
- Open Two-step verification and click the button to turn it on
- Scan the QR code with an authenticator app such as Google Authenticator or Microsoft Authenticator
- Enter the 6-digit code shown in the app and the account password, then confirm
- The page shows 8 recovery codes — only this once. Save them somewhere safe
Once it is on:
- Signing in takes the password plus the 6-digit code; without the code at hand, one recovery code can stand in for it
- The account is signed out on all other devices; only the current one stays signed in
- Fund operation verification is switched on as well — see the next section
Each recovery code works once. If the phone is lost or the authenticator app will not open, use one to sign in, or to turn two-step verification off.
| Action | Requires |
|---|---|
| Turn two-step verification off | Account password + a code from the app or one recovery code. Fund operation verification is turned off with it |
| Regenerate recovery codes | Account password + a code from the app. All old recovery codes stop working |
The secret and the recovery codes are shown once, at setup. After that they never appear on any page, in any list or in any export — the admin panel included.
Fund operation verification
A switch on the Two-step verification page. It turns on automatically with two-step verification, and changing it requires the account password and a code.
While it is on, the member must enter the current 6-digit code before:
- Paying for an order with balance
- Requesting a withdrawal (cash-out)
- Transferring balance to a sub-member
- Buying a merchant tier with balance
After a successful check there is no further prompt for 5 minutes. Members without two-step verification are not affected at all.
Watch out with integrations: store sharing and the API both go through the integration API, which servers call automatically — there is nobody to type a code. So when an account with fund operation verification on pays from its balance through the integration API, only the calling server's IP counts: the order goes through if that IP is on the account's integration IP whitelist, and an empty whitelist refuses every such order. This applies whether a downstream site integrates with your store through such an account, or you integrate with an upstream store using your own account there.
3.8.1 has no whitelist: such an account cannot spend its balance through the integration API at all, and the only way round it is to turn fund operation verification off on that account (two-step verification itself can stay on).
Integration IP whitelist
New in 3.8.2 and open to every member, whether or not two-step verification is on. It switches on with the first entry: from then on, when the integration API pays from this account's balance, only the listed IPs or ranges are accepted. Only orders are checked — fetching products, stock or order status is not affected.
| Whitelist | Fund operation verification on | Fund operation verification off |
|---|---|---|
| Has entries | Only listed sources are accepted | Only listed sources are accepted |
| Empty | Every order is refused (the integration API cannot enter a code) | No restriction, as before 3.8.2 |
It is worth setting up even without fund operation verification: if the merchant key (app_key) ever leaks, whoever has it still cannot place balance orders from an IP that is not on the list.
Where to find it:
- Default theme (原初之力): the Integration whitelist page in the user centre's security navigation, just left of Security log. With two-step verification on, the Two-step verification page also shows a one-line hint below the fund operation verification switch: an amber warning with an Add link when fund operation verification is on and the list is still empty, or the number of allowed sources with a Manage whitelist link once the list has entries
- Other themes: the whitelist appears directly on the Two-step verification page — below the fund operation verification switch when two-step verification is on, at the bottom of the page when it is off
| Item | Details |
|---|---|
| What to enter | A single IPv4 or IPv6 address, or a range in CIDR notation such as 203.0.113.0/24 |
| Widest range | /16 for IPv4 and /48 for IPv6. Anything wider, such as 0.0.0.0/0, is rejected |
| Entries and notes | Up to 20 entries per account, each with an optional note of up to 32 characters |
| Adding | Requires verification: the 6-digit code from the authenticator app if two-step verification is on, otherwise the account password |
| Removing | No verification needed — removing an entry only narrows access |
| Last allowed | Each entry shows when it last let an integration order through |
In the default theme, the top of the Integration whitelist page shows the current state:
| State | Meaning |
|---|---|
| Active | The list has entries; only listed sources are accepted |
| List is empty | Fund operation verification is on and the list is empty, so every integration order is refused |
| Not active | Fund operation verification is off and the list is empty, so nothing is restricted; adding the first IP turns the whitelist on |
Recently refused: when an integration order is refused, the error returned to the caller deliberately leaves out the IP — a downstream site may show upstream errors to its customers, which would expose the downstream server's real IP. Instead, refused IPs are listed under Recently refused below the whitelist (last 7 days, up to 5), each with a one-click button to add it to the whitelist; the same verification is still required. Every refusal is also written to the security log as a high-risk entry, at most once per IP every 10 minutes. An IP you do not recognise here means someone is placing orders with this account's merchant key (app_key) — reset the merchant key straight away.
Not sure of the server's IP? Place one integration order. As long as it is refused (fund operation verification is on, or the list already has other IPs), the server's IP appears under Recently refused, ready to add. Otherwise, look up the public egress IP on the server that calls the API and add it; once the first IP is on the list, orders from any other source are refused and listed under Recently refused.
For site owners: the caller's IP is worked out from IP detection mode and Trusted proxy IPs under Site settings → Security. If the site sits behind a CDN or reverse proxy that is not set as trusted, every integration call appears to come from the CDN's IP — members would end up whitelisting CDN IPs, and the whitelist would protect nothing. Set up trusted proxies first.
Sign-in devices
From 3.8.1, one account can stay signed in on several devices at once. Older versions signed the previous device out whenever the account signed in on a new one.
The Sign-in Devices page lists every device that is signed in: device type, system and browser, and the IP and time of both the sign-in and the latest activity. The device in use right now is marked Current Device.
Devices can be signed out one at a time, or in bulk with Sign Out Other Devices or Sign Out All Devices. If an unfamiliar device shows up, sign it out first, then change the password.
Security log
Important actions on the account are recorded, each with time, IP and browser:
| Category | Events |
|---|---|
| Sign-in | Successful sign-in (including passkey sign-in), failed sign-in, sign-out |
| Account details | Changing the password, email, phone number, profile or payout method |
| Verification settings | Turning two-step verification on or off, turning fund operation verification on or off, passing fund operation verification, regenerating recovery codes |
| Devices and keys | Signing a device out, adding or removing a passkey, resetting the merchant key (app_key) |
| Funds | Withdrawal requests, transfers to sub-members |
| Integration whitelist | Adding or removing an integration whitelist IP, a refused integration order (caller's IP not on the whitelist) |
Higher-risk events carry a High Risk tag — for example a sign-in from a different IP than last time, a failed sign-in, turning two-step verification off, resetting the merchant key, adding an integration whitelist IP, or a refused integration order. Risky only narrows the list to those.
The log does not store email addresses, phone numbers or payout accounts.
Viewing it as an admin: in the admin panel's Members list, every row has a Security log button (shield icon) that opens that member's log, filterable by type, details, IP and time. An admin resetting a member's password from the admin panel is logged too. From 3.8.2, only the main admin account (the one created during installation) can use this button; Super Administrator, Day Shift and Night Shift accounts get a no-permission message.
Passkeys
Sign in with a fingerprint, face or the device's screen-lock PIN instead of a password. The passkey is kept on the member's own device or in their password manager, so a phishing site cannot capture it.
Adding one: open Passkeys → click Add Passkey → enter the account password → complete the check the device asks for. Up to 10 per account; each can be renamed or deleted.
Signing in: on the sign-in page click Sign in with a passkey, or click the account field and pick the passkey from the autofill list, then confirm with fingerprint, face or PIN.
With two-step verification on, a passkey sign-in confirmed on the device with fingerprint, face or PIN skips the 6-digit code. Without that check — for example a hardware security key with no PIN — the code is still required.
Passkeys have requirements:
| Requirement | Details |
|---|---|
| HTTPS and a domain | The site must be opened at https://your-domain; plain http or an IP address will not work |
| A system browser | In-app browsers, such as the ones inside WeChat, QQ or Alipay, are not supported |
| The same domain | A passkey only works on the exact domain it was added on. With and without www count as two domains, and every sub-store domain is separate |
If either of the first two is not met, the sign-in page does not show the Sign in with a passkey button.
Other themes
The default theme (原初之力) has all of these pages. Other themes with a user centre — Los Angeles, Mount Fuji, New York, Seattle, Shibuya, Rudeus and others — get them through their own theme updates: update those themes to the latest version in the app store. These themes have no separate Integration whitelist page; the whitelist appears on the Two-step verification page — below the fund operation verification switch when two-step verification is on, at the bottom of the page when it is off.
Whichever theme is in use, members with two-step verification on can still sign in normally.
For admins
Passkey sign-in
Admins can sign in to the admin panel with a passkey instead of a password.
- Click your avatar in the top-right corner to open Personal settings
- In the Passkeys section, click Add Passkey
- Enter your current sign-in password
- Confirm with fingerprint, face, Windows Hello, a phone or a security key
From then on, click Sign in with a passkey on the admin sign-in page. Password sign-in keeps working, and a passkey can also unlock the idle lock screen. HTTPS is required here too, and the passkey only works on the domain used when adding it.
For admins with Google Authenticator turned on:
| Passkey | At sign-in |
|---|---|
| Confirmed on the device with fingerprint, face or PIN | Signs in directly, no Google Authenticator code |
| No such check (for example a plain security key without a PIN) | Still asks for the Google Authenticator code |
Changing an admin's password does not revoke their passkeys. To take away someone's admin access, disable or delete that admin account.
Idle lock screen
On by default after the upgrade, at 15 minutes. Change it under Site settings → Security → Admin Idle Lock: 0–1440 minutes, and 0 turns it off. See site settings.
- With no mouse, keyboard or touch activity for that long, the admin panel locks
- Unlock with your sign-in password or a passkey, or choose Sign in with another account
- The server decides when to lock. Pages that refresh their own data do not count as activity, and devices signed in with Stay signed in lock too
- Locking navigates away from the current page — save any edits first
- The upgrade itself does not sign admins out
New sign-in page
The admin sign-in page now looks like the macOS lock screen: a clock and a glass-style input group.
- Switch language and appearance (light / dark / follow system) from the top-right corner
- Errors appear right under the field they belong to, and a hint shows when Caps Lock is on
- For accounts with Google Authenticator, the code field opens in place inside the form
- With no custom background — or with the default one — built-in wallpapers follow light and dark mode. A custom background still works as before
The default background image itself has changed. Sites still using the default Desktop Background will see the new image on the storefront and user centre too. To keep the old one, save a copy of
/assets/admin/images/login/bg.jpgfrom your site before upgrading, then upload it as the Desktop Background under Site settings → General afterwards.
Common problems
| Problem | What to do |
|---|---|
| No Sign in with a passkey button on the sign-in page | Open the site at https://your-domain in a system browser — not the built-in browser of WeChat, QQ or Alipay |
| A member lost their phone and cannot see codes | Sign in with a recovery code, turn two-step verification off, then turn it on again on the new phone |
| The admin panel locks too often | Raise Admin Idle Lock under Site settings → Security, or set it to 0 |
| Integration orders fail with "该账号已开启资金二次验证，必须先登记对接白名单 IP 才能通过对接接口用余额下单。请登录该账号的会员中心，在「对接白名单」（或「两步验证」页）把服务器 IP 加入白名单；被拒的 IP 会列在那里" (fund verification is on, so an IP must be on the integration whitelist before balance orders work) | The upstream runs 3.8.2 or later, the account has fund operation verification on and its whitelist is still empty. Sign in to that account's user centre, open the Integration whitelist page (in other themes, the Two-step verification page) and add the server IP listed under Recently refused to the integration IP whitelist |
| Integration orders fail with "调用方 IP 不在该账号的对接白名单内。请登录该账号的会员中心，在「对接白名单」（或「两步验证」页）把服务器 IP 加入白名单；被拒的 IP 会列在那里" (the caller's IP is not on this account's integration whitelist) | The upstream runs 3.8.2 or later, the account has a whitelist, and the calling server's IP is not on it. Add it from Recently refused in the same way. If you do not recognise the IP, the merchant key may have leaked — reset it first |
| Integration orders fail with "该账号已开启资金二次验证，无法通过对接接口消费余额" (the balance cannot be spent through the integration API) | The upstream runs 3.8.1, which has no whitelist. Turn fund operation verification off on that account's Two-step verification page, or ask the upstream to upgrade to 3.8.2 and use the whitelist |
| The member Security log button in the admin panel says you have no permission | From 3.8.2, only the main admin account (the one created during installation) can view members' security logs |
| Every member was signed out after the upgrade | Expected. Each member signs in once more |
| A passkey stopped working after a domain change | Passkeys are bound to the domain they were added on. Add a new one on the new domain |