App Users
Let customers sign in to an app you built on Busabase with an email code, see only their own orders and records, and manage those accounts without giving anyone a seat.
Your shop's buyers want to see their orders again next week. A members-only page needs to know who is reading it. App users give the people who use your app an account of their own: they sign in with a code sent to their email, see only their own rows, and never see Busabase or take up a seat.
App users are available on Busabase Cloud, for apps published as a website.
App users, members and guests
| Who | Who they are | What they get |
|---|---|---|
| Members | Your team | Open the space in Busabase, use a seat, work with Bases, Docs and apps according to their permissions |
| App users | The people your app serves, such as shop buyers | Sign in to your app only. No seat, no Busabase screens, no password. They see what your app shows them, and only their own rows |
| Guests | People who use your app without signing in | Whatever the app offers publicly, such as browsing products or guest checkout |
There is one pool of app users per space. If someone signs in to two of your apps with the same email, they are one app user who has used both. App users are never members, and becoming one does not give anyone access to your workspace.
Turn on sign-in for an app
You need Manage access on the app, and on Busabase Cloud the space must be on Plus or above (a trial counts). On Free the switch is locked and shows an upgrade button. If a space drops back to Free with sign-in on, no new codes are sent, people already signed in stay signed in until their session expires, and you can still turn sign-in off.
- Open the app and go to Settings → User sign-in.
- Turn on Let people sign in to this app.
- Fill in Name in emails. This is the name buyers see as the sender and in the subject of the sign-in email. Leave it empty to use the app's name.
- Click Save.
That is all there is to set. Busabase stores the accounts itself, so you never need a users table.
Whose rows are whose
Which rows belong to which buyer is decided by the app itself, not by a setting. The app keeps the buyer's id in an App user column (or an ordinary text column), such as customer-account in an Orders table: when a signed-in buyer places an order, the app's server writes their app user id there. When the buyer opens "My orders", the app asks Busabase for the rows whose customer-account matches the signed-in buyer, and Busabase fills in the buyer's id from their verified sign-in. No one can ask for someone else's id.
- A row with an empty owner column belongs to nobody. Guest orders stay that way.
- An App user column shows each id as the buyer's email, marks disabled buyers, and shows Deleted app user for an account that was deleted. Click an email to see the buyer's status, last sign-in and apps, with a link to Manage app users. Space owners and admins can pick a buyer by email when editing a row; other members can keep or clear the value.
- Already have a text column of ids? Change its type to App user in the column settings. Every value is kept.
- When you export a template, App user values are left out: the ids belong to this space's buyers and mean nothing in another space. The column itself is kept.
Turning sign-in off signs everyone out
Turning Let people sign in to this app off ends every session for that app at once. Guest features keep working if the app was built to handle it (see For developers).
What your buyers see
- They enter their email in your app.
- They receive a 6-digit code. There is no password to create or forget.
- They type the code and are signed in for 30 days on that browser.
The code is valid for 10 minutes and can be tried 5 times. Asking for a new code makes older ones stop working.
The email names your app (the Name in emails setting, or else the app's name) and never mentions Busabase. It is written in the language your app asks for: English, Simplified Chinese, Traditional Chinese, Japanese, Korean, German, French, Spanish, Portuguese or Vietnamese. Any other language falls back to English.
Sign-in limits
To keep your app from being used to send spam, Busabase limits how often codes can be sent. When a limit is hit, the app gets a RATE_LIMITED answer with a reason and the number of seconds to wait (retryAfterSeconds). The limits are checked in this order:
reason | Limit | What the app should tell the buyer |
|---|---|---|
cooldown | One code per email every 60 seconds | "We just sent a code. You can ask for another in N seconds." |
ip_hourly_limit | 5 codes per hour from one network, per app | "Too many attempts from this network. Try again later." |
ip_daily_limit | 20 codes per day from one network, per app | Same as above |
email_daily_limit | 10 codes per email per day | "Too many codes for this address today. Try again tomorrow." |
space_daily_limit | 1000 codes per space per day, counted only for addresses that are not yet app users | "Sign-in is busy right now. Try again later." |
Returning customers are never locked out by space_daily_limit: only new addresses count toward it, so someone sending codes to random addresses cannot stop your existing buyers from signing in.
The per-network limits apply only when your app passes the buyer's IP address along with the request. Busabase stores only a keyed hash of that address, never the address itself.
Manage app users
Open Space Settings → App users to see everyone who has signed in to your apps.
- Search by email and Filter by app to find someone. The list shows each person's status, last sign-in, the apps they have used, and when the account was created. Click Load more to see older accounts.
- Disable stops someone from signing in and signs them out of every app at once. Enable lets them sign in again.
- Delete removes the account, its codes and its sessions. Their orders and other records stay where they are. If they sign in again later, they get a new account.
Who can do what:
| Role | Can |
|---|---|
| Space owner or admin | See all app users, disable, enable and delete them |
| Member with Manage access on one app | From that app's Settings → User sign-in → Manage app users, see the people who signed in to that app, read-only. Change that app's sign-in settings |
| Other members | Read an app's sign-in settings |
Every disable, enable and delete, and every change to an app's sign-in settings, is recorded in the Cloud audit log with the member and API key that made it.
From the CLI or an agent
The same administration is available from the CLI:
busabase-cli app-users list --email buyer@example.com # or --app-id <app id>
busabase-cli app-users disable --id <app user id>
busabase-cli app-users enable --id <app user id>
busabase-cli app-users delete --id <app user id>
busabase-cli app-users get-settings --app-id <app id>
busabase-cli app-users put-settings --app-id <app id> --enabled --app-name "Kelly's Shop"
busabase-cli app-users put-settings --app-id <app id> --no-enabled # turn sign-in off (signs everyone out)Through MCP, agents get the tools app_users_list, app_users_disable, app_users_enable, app_users_delete, app_users_get_settings and app_users_put_settings. Agents cannot send sign-in codes or act as an app user: those steps belong to your app's server only.
Privacy
- Deleting an app user removes the account, its codes and its sessions. Business rows such as orders are kept. Their owner column still holds the old id, which no future account can ever match.
- Busabase stores sign-in codes, session tokens and IP addresses only as hashes.
- Old sign-in codes are cleaned up automatically after 48 hours.
For developers
Everything an app does with app users happens on the app's own server (for a website, its Worker), using the API key the site already has. The browser only talks to your app's own routes, such as /account/send-code, and never sees the API key.
Sign-in flow with the SDK
import {
Busabase,
appUserSessionCookie,
clearAppUserSessionCookie,
getAppUserSessionToken,
} from "busabase-sdk";
const bb = new Busabase({
baseUrl: env.BUSABASE_BASE_URL,
apiKey: env.BUSABASE_API_KEY,
spaceId: env.BUSABASE_SPACE_ID,
});
const appId = "<app node id>";
// 1. POST /account/send-code: email the buyer a code, in the shop's language.
await bb.appUsers.sendCode({
appId,
email,
locale: "en",
ip: request.headers.get("CF-Connecting-IP") ?? undefined,
});
// 2. POST /account/verify: exchange the code for a session, keep it in an HttpOnly cookie.
const { sessionToken } = await bb.appUsers.verify({ appId, email, code });
return new Response(null, {
status: 303,
headers: { Location: "/account", "Set-Cookie": appUserSessionCookie(sessionToken) },
});
// 3. GET /account: who is signed in, and their own orders.
const token = getAppUserSessionToken(request);
const user = await bb.appUsers.getUser({ appId, sessionToken: token }); // null when signed out
if (user) {
const { records, nextCursor } = await bb.appUsers.queryRecords({
appId,
sessionToken: token,
baseId: "orders",
ownerField: "customer-account", // the App user (or text) column that holds the buyer's id
limit: 20,
});
}
// 4. POST /account/sign-out
await bb.appUsers.signOut({ appId, sessionToken: token });
return new Response(null, {
status: 303,
headers: { Location: "/", "Set-Cookie": clearAppUserSessionCookie() },
});- Pass
localeso the email matches your site's language, andip(the buyer's address, fromCF-Connecting-IPor the firstX-Forwarded-Forhop) so the per-network limits protect you. - When a signed-in buyer creates a row, such as an order, write
user.idinto the owner column on the server, from the session. Never take it from what the browser sends. Write the buyer's verifieduser.emailinto a separate email column the same way. queryRecordstakesownerField, the slug of the App user (or text) column that holds the app user id. Your server chooses the column; Busabase fills in the value from the verified session and enforcesownerField = signed-in user id: another user's rows are simply not there.
Never filter a user's rows yourself
Do not read a Base with the site's key and filter the result in your code to find "this buyer's orders". The site key can read every row, so one bug shows one customer another customer's orders. Always use bb.appUsers.queryRecords (POST /api/v1/app-users/records/query) with ownerField, where Busabase applies the owner filter with the signed-in user's id.
Errors to handle
Errors carry a code, and extra details in data:
code | When | What to do |
|---|---|---|
APP_LOGIN_DISABLED | Sign-in is off for this app | Hide the account UI |
INVALID_EMAIL | The address is not a valid email | Ask the buyer to check it |
RATE_LIMITED | A limit was hit; data.reason, data.retryAfterSeconds | Show the message from the table above |
INVALID_CODE | Wrong code; data.attemptsLeft | Ask them to try again |
CODE_EXPIRED | Code too old, used up, or never sent | Offer to send a new one |
APP_USER_DISABLED | The account was disabled | Say this account can't sign in |
APP_USER_SESSION_INVALID | Session missing, expired, revoked or for another app | Clear the cookie and show the sign-in form (getUser returns null for you) |
INVALID_OWNER_FIELD | ownerField is not an App user or text column of that table | Fix the column slug in the app's code |
Keep guest flows working
Sign-in is optional, and the app must still work without it. Read the settings once with bb.appUsers.getSettings({ appId }): if it says enabled: false, or the request fails with a 404 (an older server without app users), hide every account link and keep guest checkout and other public features exactly as they were.
Publish an AirApp as a Website
Use the Website engine to put an AirApp at a public address that stays online, connect your own domain, and let the site read and write the workspace through the Busabase API.
Templates
Give your agent business context, data, and instructions, then keep working through conversation and see the results in Busabase.