Busabase

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

WhoWho they areWhat they get
MembersYour teamOpen the space in Busabase, use a seat, work with Bases, Docs and apps according to their permissions
App usersThe people your app serves, such as shop buyersSign in to your app only. No seat, no Busabase screens, no password. They see what your app shows them, and only their own rows
GuestsPeople who use your app without signing inWhatever 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.

  1. Open the app and go to Settings → User sign-in.
  2. Turn on Let people sign in to this app.
  3. 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.
  4. 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

  1. They enter their email in your app.
  2. They receive a 6-digit code. There is no password to create or forget.
  3. 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:

reasonLimitWhat the app should tell the buyer
cooldownOne code per email every 60 seconds"We just sent a code. You can ask for another in N seconds."
ip_hourly_limit5 codes per hour from one network, per app"Too many attempts from this network. Try again later."
ip_daily_limit20 codes per day from one network, per appSame as above
email_daily_limit10 codes per email per day"Too many codes for this address today. Try again tomorrow."
space_daily_limit1000 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:

RoleCan
Space owner or adminSee all app users, disable, enable and delete them
Member with Manage access on one appFrom 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 membersRead 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 locale so the email matches your site's language, and ip (the buyer's address, from CF-Connecting-IP or the first X-Forwarded-For hop) so the per-network limits protect you.
  • When a signed-in buyer creates a row, such as an order, write user.id into the owner column on the server, from the session. Never take it from what the browser sends. Write the buyer's verified user.email into a separate email column the same way.
  • queryRecords takes ownerField, 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 enforces ownerField = 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:

codeWhenWhat to do
APP_LOGIN_DISABLEDSign-in is off for this appHide the account UI
INVALID_EMAILThe address is not a valid emailAsk the buyer to check it
RATE_LIMITEDA limit was hit; data.reason, data.retryAfterSecondsShow the message from the table above
INVALID_CODEWrong code; data.attemptsLeftAsk them to try again
CODE_EXPIREDCode too old, used up, or never sentOffer to send a new one
APP_USER_DISABLEDThe account was disabledSay this account can't sign in
APP_USER_SESSION_INVALIDSession missing, expired, revoked or for another appClear the cookie and show the sign-in form (getUser returns null for you)
INVALID_OWNER_FIELDownerField is not an App user or text column of that tableFix 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.

On this page