@quickback-dev/cli 0.72.8 → 0.72.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +1 -1
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +2 -2
- package/dist/skill/docs/configure/single-tenant.md +1 -0
- package/dist/skill/docs/platform/auth/plugins/organization-defaults.md +37 -0
- package/dist/skill/docs/platform/auth/using-auth.md +2 -0
- package/dist/skill/docs/ui/account/customization.md +2 -2
- package/dist/skill/docs/ui/account/environment-variables.md +7 -1
- package/dist/skill/docs/ui/account/features/admin.md +2 -2
- package/dist/skill/docs/ui/account/features/api-keys.md +1 -1
- package/dist/skill/docs/ui/account/features/index.md +10 -8
- package/dist/skill/docs/ui/account/features/organizations.md +19 -9
- package/dist/skill/docs/ui/account/features/passkeys.md +6 -2
- package/dist/skill/docs/ui/account/features/sessions.md +2 -2
- package/dist/skill/docs/ui/account/index.md +61 -30
- package/dist/skill/docs/ui/account/with-quickback.md +1 -1
- package/dist/skill/docs/ui/admin/connecting.md +1 -1
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/package.json +1 -1
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +2 -2
- package/src/skill/docs/configure/single-tenant.md +1 -0
- package/src/skill/docs/platform/auth/plugins/organization-defaults.md +37 -0
- package/src/skill/docs/platform/auth/using-auth.md +2 -0
- package/src/skill/docs/ui/account/customization.md +2 -2
- package/src/skill/docs/ui/account/environment-variables.md +7 -1
- package/src/skill/docs/ui/account/features/admin.md +2 -2
- package/src/skill/docs/ui/account/features/api-keys.md +1 -1
- package/src/skill/docs/ui/account/features/index.md +10 -8
- package/src/skill/docs/ui/account/features/organizations.md +19 -9
- package/src/skill/docs/ui/account/features/passkeys.md +6 -2
- package/src/skill/docs/ui/account/features/sessions.md +2 -2
- package/src/skill/docs/ui/account/index.md +61 -30
- package/src/skill/docs/ui/account/with-quickback.md +1 -1
- package/src/skill/docs/ui/admin/connecting.md +1 -1
- package/src/skill/docs/ui/admin/index.md +1 -1
package/dist/index.js
CHANGED
|
@@ -172,7 +172,7 @@ When the compiler builds the Account SPA, it excludes route files for disabled f
|
|
|
172
172
|
|
|
173
173
|
| Feature Flag | Routes Excluded When `false` |
|
|
174
174
|
|-------------|------------------------------|
|
|
175
|
-
| `auth.organizations` |
|
|
175
|
+
| `auth.organizations` | Org switcher, Home org list + invitations, org pages (`/$slug`: General, Members, Teams, Billing) |
|
|
176
176
|
| `auth.passkey` | Passkey management and setup |
|
|
177
177
|
| `auth.admin` | Admin panel routes |
|
|
178
178
|
|
|
@@ -699,7 +699,7 @@ account: {
|
|
|
699
699
|
|--------|------|-------------|
|
|
700
700
|
| `domain` | `string` | Custom domain for Account UI (e.g., `auth.example.com`) |
|
|
701
701
|
| `adminDomain` | `string` | Custom domain for admin-only access (e.g., `admin.example.com`). Serves the same Account SPA — the client-side router handles admin routing. |
|
|
702
|
-
| `appUrl` | `string` | Origin of the tenant's main application. Baked into the Account SPA as `VITE_QUICKBACK_APP_URL`. Combined with `tenantPattern` for
|
|
702
|
+
| `appUrl` | `string` | Origin of the tenant's main application. Baked into the Account SPA as `VITE_QUICKBACK_APP_URL`. Combined with `tenantPattern` for every **Open** button (top bar, Home, org switcher). Independent from `domain`. A deploy-target `APP_URL` can override this at serve time. |
|
|
703
703
|
| `tenantPattern` | `string` | URL pattern for a tenant, with `{slug}` substituted. Default `/{slug}`. Relative patterns are resolved against `appUrl`; a full `https://{slug}.example.com` pattern is used as-is. Baked as `VITE_TENANT_URL_PATTERN`. |
|
|
704
704
|
| `name` | `string` | App display name shown on login, profile, and email templates |
|
|
705
705
|
| `companyName` | `string` | Company name for branding |
|
|
@@ -718,7 +718,7 @@ Control which authentication features are exposed. Disabled features are hidden
|
|
|
718
718
|
| `auth.emailOTP` | `boolean` | `false` | adds `emailOtp` plugin | Email one-time password login — adds plugin server-side, surfaces UI |
|
|
719
719
|
| `auth.passkey` | `boolean` | `false` | adds `passkey` plugin | WebAuthn/FIDO2 passkey authentication — adds plugin server-side, surfaces UI |
|
|
720
720
|
| `auth.signup` | `boolean` | `true` | `signup.inviteOnly` (inverted) | Self-service account registration — false hides open signup in the UI **and** makes the server [invite-only](/platform/auth/security#signup-policy): every sign-in method refuses new accounts with 403 `SIGNUP_NOT_ALLOWED` unless the email holds a pending invitation |
|
|
721
|
-
| `auth.organizations` | `boolean` | `true` | UI surface only | Organization
|
|
721
|
+
| `auth.organizations` | `boolean` | `true` | UI surface only | Organization UI: the switcher, the org list and invitations on Home, and the org pages. Sign-in lands on `/home`. Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
|
|
722
722
|
| `auth.admin` | `boolean` | `false` | UI surface only | Admin panel for user management in the Account SPA. The Better Auth admin plugin is compiler-managed separately from this UI toggle |
|
|
723
723
|
| `auth.emailVerification` | `boolean` | `false` | `emailAndPassword.requireEmailVerification` | Require email verification before sessions are issued. False = sessions usable immediately after signup |
|
|
724
724
|
|
|
@@ -94,6 +94,7 @@ When `features.pinnedOrganizationId` is set:
|
|
|
94
94
|
- the CMS skips the org-selection gate
|
|
95
95
|
- API calls and realtime connections use the pinned org automatically
|
|
96
96
|
- role checks still come from the caller's membership in that org
|
|
97
|
+
- a member's new sessions start with the pinned org active ([Organization Defaults](/platform/auth/plugins/organization-defaults))
|
|
97
98
|
|
|
98
99
|
This is the intended replacement for the old single-tenant CMS flow.
|
|
99
100
|
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Organization Defaults
|
|
2
|
+
|
|
3
|
+
Every Better Auth project ships `organizationDefaults()`, a Better Auth plugin the compiler emits into `src/plugins/organization-defaults/` and adds to `src/lib/auth.ts` alongside `organization()`. It needs no configuration.
|
|
4
|
+
|
|
5
|
+
## Reserved organization slugs
|
|
6
|
+
|
|
7
|
+
An organization slug becomes a URL segment: `/account/<slug>` in the Account UI, and `<appUrl>/<slug>` in your app with the default `tenantPattern`. A slug that matches a route shadows it. An organization called `security` could never open its own page, and one called `admin` or `support` impersonates something it isn't.
|
|
8
|
+
|
|
9
|
+
The plugin refuses about 150 reserved slugs with `400` and `code: "ORGANIZATION_SLUG_RESERVED"` on:
|
|
10
|
+
|
|
11
|
+
- `POST /auth/v1/organization/create`
|
|
12
|
+
- `POST /auth/v1/organization/update` (renaming the slug)
|
|
13
|
+
- `POST /auth/v1/organization/check-slug`, so the Account UI's "is this URL available" check agrees with the write
|
|
14
|
+
- the operator route `POST /auth/v1/admin/create-organization`, which writes the row directly and applies the same rule
|
|
15
|
+
|
|
16
|
+
Matching is exact and case-insensitive: `home` is reserved, `home-depot` is not. The list covers:
|
|
17
|
+
|
|
18
|
+
- every top-level Account UI route (`home`, `profile`, `security`, `dashboard`, `login`, …)
|
|
19
|
+
- auth and account words (`settings`, `billing`, `members`, `invite`, `oauth`, …)
|
|
20
|
+
- platform paths (`api`, `cms`, `app`, `static`, `webhooks`, `www`, …)
|
|
21
|
+
- roles and system accounts (`admin`, `root`, `sysadmin`, `superuser`, `system`, …)
|
|
22
|
+
- common shell commands (`sudo`, `ls`, `rm`, `cd`, `git`, `curl`, …)
|
|
23
|
+
- values that read as code (`null`, `undefined`, `true`, `localhost`, `env`, …)
|
|
24
|
+
|
|
25
|
+
The full list is `RESERVED_ORGANIZATION_SLUGS` in `src/plugins/organization-defaults/reserved-slugs.ts`. A compiler test fails if a new top-level Account UI route is missing from it.
|
|
26
|
+
|
|
27
|
+
Organizations that already hold a reserved slug keep it. Updates that don't change the slug still work, but the org's Account page is shadowed by the route until it is renamed.
|
|
28
|
+
|
|
29
|
+
## Default active organization
|
|
30
|
+
|
|
31
|
+
New sessions start with no active organization, so the app, the CMS, and org-scoped API calls have nothing to default to. The plugin fills that gap when the choice is unambiguous:
|
|
32
|
+
|
|
33
|
+
- **Pinned project** (`features.pinnedOrganizationId`): a member of the pinned organization starts every session in it.
|
|
34
|
+
- **One membership**: the session starts in that organization.
|
|
35
|
+
- **Several memberships, or none**: nothing is chosen; the user picks an organization in the app or the Account UI.
|
|
36
|
+
|
|
37
|
+
It never overrides an active organization the session already carries. The Account UI applies the same rule client-side for sessions created before the plugin existed.
|
|
@@ -89,6 +89,8 @@ When organizations are enabled, the active organization is on the auth context a
|
|
|
89
89
|
const orgId = c.get('ctx').activeOrgId;
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
+
A new session starts in the user's organization when the choice is unambiguous (the pinned organization, or their only membership). With several memberships, `activeOrgId` stays unset until the user picks one. See [Organization Defaults](/platform/auth/plugins/organization-defaults).
|
|
93
|
+
|
|
92
94
|
> **`activeOrgId`, not `activeOrganizationId`**
|
|
93
95
|
>
|
|
94
96
|
> `activeOrganizationId` is Better Auth's *session* field name (`session.session.activeOrganizationId`). Quickback canonicalises it to `ctx.activeOrgId`; firewall rules written against `ctx.activeOrganizationId` are rewritten to `ctx.activeOrgId` at compile time.
|
|
@@ -93,7 +93,7 @@ setAppConfig({
|
|
|
93
93
|
| `privacy` | "Privacy Policy" | Footer link text |
|
|
94
94
|
| `support` | "Contact Support" | Footer link text |
|
|
95
95
|
| `company` | (from `VITE_COMPANY_NAME`) | Footer company name |
|
|
96
|
-
| `organizations` | "Organizations" | Navigation and
|
|
96
|
+
| `organizations` | "Organizations" | Navigation, the switcher, and Home. The singular form (trailing `s` dropped) labels **New …** and **… settings**, so `"Workspaces"` gives **New workspace**. |
|
|
97
97
|
|
|
98
98
|
## Custom Messages
|
|
99
99
|
|
|
@@ -153,7 +153,7 @@ setAppConfig({
|
|
|
153
153
|
welcome: '/getting-started',
|
|
154
154
|
},
|
|
155
155
|
authenticated: {
|
|
156
|
-
|
|
156
|
+
home: '/home',
|
|
157
157
|
profile: '/my-account',
|
|
158
158
|
settings: '/preferences',
|
|
159
159
|
},
|
|
@@ -149,6 +149,7 @@ Enable or disable features using boolean environment variables. **Every flag car
|
|
|
149
149
|
|---|---|---|
|
|
150
150
|
| `VITE_ENABLE_ORGANIZATIONS` | `organizations` | `false` |
|
|
151
151
|
| `VITE_ENABLE_ORG_TEAMS` | `orgTeams` | `false` |
|
|
152
|
+
| `VITE_ENABLE_ORG_CREATION` | `orgCreation` | `false` |
|
|
152
153
|
| `VITE_ENABLE_ADMIN` | `admin` | `false` |
|
|
153
154
|
| `VITE_ENABLE_FILE_UPLOADS` | `fileUploads` | `false` |
|
|
154
155
|
| `VITE_ENABLE_PASSKEY` | `passkey` | `false` |
|
|
@@ -193,7 +194,12 @@ VITE_ENABLE_REALTIME=false # default: false
|
|
|
193
194
|
VITE_ENABLE_ORGANIZATIONS=false # default: false
|
|
194
195
|
VITE_ENABLE_ORG_TEAMS=false # default: false
|
|
195
196
|
# Auto-set to true when the BA config has organization({ teams: { enabled: true } }).
|
|
196
|
-
# When false the Teams
|
|
197
|
+
# When false the Teams page is hidden and the auth client doesn't expose team APIs.
|
|
198
|
+
VITE_ENABLE_ORG_CREATION=false # default: false
|
|
199
|
+
# Auto-set to true when the BA config sets
|
|
200
|
+
# plugins.organization.allowUserToCreateOrganization: true. When false there is no
|
|
201
|
+
# "New organization" button and /organizations/new redirects home (the server
|
|
202
|
+
# closes POST /organization/create; operators create orgs from Admin).
|
|
197
203
|
|
|
198
204
|
# Admin
|
|
199
205
|
VITE_ENABLE_ADMIN=false # default: false — the compiler always emits it explicitly
|
|
@@ -72,7 +72,7 @@ curl -X POST https://api.example.com/auth/v1/admin/set-role \
|
|
|
72
72
|
|
|
73
73
|
Better Auth's `organization.create` seats whoever calls it. For an operator that is an escalation rather than a convenience: the membership it grants is tenant-data access — under `cms.access: "member"`, access to that organization's records — which is exactly what the `appmanager`/`sysadmin` split withholds.
|
|
74
74
|
|
|
75
|
-
So organization creation asks for an `ownerUserId`, seats that user, and never seats the caller. Self-serve creation (`POST /auth/v1/organization/create`) is closed by default for the same reason; a project that wants it sets `plugins.organization.allowUserToCreateOrganization: true`.
|
|
75
|
+
So organization creation asks for an `ownerUserId`, seats that user, and never seats the caller. Self-serve creation (`POST /auth/v1/organization/create`) is closed by default for the same reason; a project that wants it sets `plugins.organization.allowUserToCreateOrganization: true`. Account UI follows the same setting: it shows **New organization** (and serves `/organizations/new`) only when that option is `true`. Both routes refuse [reserved slugs](/platform/auth/plugins/organization-defaults#reserved-organization-slugs).
|
|
76
76
|
|
|
77
77
|
An operator who genuinely wants their own organization creates one naming themselves as owner — explicit, and visible in the audit trail rather than implied by whoever happened to make the call.
|
|
78
78
|
|
|
@@ -127,7 +127,7 @@ The admin domain serves the same Account SPA at root (`/`). The SPA's client-sid
|
|
|
127
127
|
|
|
128
128
|
## CMS Access Control
|
|
129
129
|
|
|
130
|
-
When both CMS and Account UI are enabled, the Account
|
|
130
|
+
When both CMS and Account UI are enabled, the Account top bar and Home show a CMS action. It opens the current (or sole) organization directly, or lets a multi-organization user choose one first. You can restrict this to the sysadmin tier only:
|
|
131
131
|
|
|
132
132
|
```typescript
|
|
133
133
|
cms: { domain: "cms.example.com", access: "sysadmin" },
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# API Key Management
|
|
2
2
|
|
|
3
|
-
API keys are a user credential. Manage them at `/api-keys
|
|
3
|
+
API keys are a user credential. Manage them at `/api-keys` (**API keys** under Account in the sidebar). The `apiKey` plugin is on by default.
|
|
4
4
|
|
|
5
5
|
## Creating API Keys
|
|
6
6
|
|
|
@@ -11,18 +11,20 @@ Control which features are available in your Account UI deployment using feature
|
|
|
11
11
|
|
|
12
12
|
### `appConfig.features`
|
|
13
13
|
|
|
14
|
-
These
|
|
14
|
+
These thirteen flags populate `appConfig.features` and are the ones `isFeatureEnabled()` accepts.
|
|
15
15
|
|
|
16
16
|
| Variable | `features` key | Default |
|
|
17
17
|
|---|---|---|
|
|
18
18
|
| `VITE_ENABLE_ORGANIZATIONS` | `organizations` | `false` |
|
|
19
19
|
| `VITE_ENABLE_ORG_TEAMS` | `orgTeams` | `false` |
|
|
20
|
+
| `VITE_ENABLE_ORG_CREATION` | `orgCreation` | `false` |
|
|
20
21
|
| `VITE_ENABLE_ADMIN` | `admin` | `false` |
|
|
21
22
|
| `VITE_ENABLE_FILE_UPLOADS` | `fileUploads` | `false` |
|
|
22
23
|
| `VITE_ENABLE_PASSKEY` | `passkey` | `false` |
|
|
23
24
|
| `VITE_ENABLE_EMAIL_OTP` | `emailOTP` | `false` |
|
|
24
25
|
| `VITE_ENABLE_PASSWORD` | `password` | `true` |
|
|
25
26
|
| `VITE_ENABLE_GOOGLE_OAUTH` | `googleOAuth` | `false` |
|
|
27
|
+
| `VITE_ENABLE_CLOUDFLARE_OAUTH` | `cloudflareOAuth` | `false` |
|
|
26
28
|
| `VITE_ENABLE_SUBSCRIPTIONS` | `subscriptions` | `false` |
|
|
27
29
|
| `VITE_ENABLE_REALTIME` | `realtime` | `false` |
|
|
28
30
|
| `VITE_ENABLE_API_KEYS` | `apiKeys` | `true` |
|
|
@@ -176,10 +178,10 @@ VITE_ENABLE_GOOGLE_OAUTH=false # default: false
|
|
|
176
178
|
|
|
177
179
|
**When enabled:**
|
|
178
180
|
- "Continue with Google" button on the login and signup pages
|
|
179
|
-
- Google row
|
|
181
|
+
- Google row under **Connected accounts** on `/security`
|
|
180
182
|
|
|
181
183
|
**When disabled:**
|
|
182
|
-
- No social sign-in button
|
|
184
|
+
- No social sign-in button and no **Connected accounts** card on `/security`
|
|
183
185
|
|
|
184
186
|
**Requirements:**
|
|
185
187
|
- Google OAuth credentials configured on the Better Auth side
|
|
@@ -192,7 +194,7 @@ VITE_ENABLE_CLOUDFLARE_OAUTH=false # default: false
|
|
|
192
194
|
|
|
193
195
|
**When enabled:**
|
|
194
196
|
- "Continue with Cloudflare" button on the login and signup pages
|
|
195
|
-
- Cloudflare rows on `/
|
|
197
|
+
- Cloudflare rows under **Connected accounts** on `/security` — unlike
|
|
196
198
|
Google, more than one Cloudflare identity can be linked to the same user
|
|
197
199
|
(**Connect another Cloudflare account**), and every linked identity signs
|
|
198
200
|
in to this user. Link work and personal Cloudflare logins here so each one
|
|
@@ -265,11 +267,11 @@ VITE_ENABLE_ORGANIZATIONS=false # default: false
|
|
|
265
267
|
```
|
|
266
268
|
|
|
267
269
|
**When enabled:**
|
|
268
|
-
- `/
|
|
269
|
-
-
|
|
270
|
+
- Home (`/home`) lists your organizations, each with **Open** / **CMS** / settings, plus pending invitations
|
|
271
|
+
- The organization switcher in the top bar (a plain label with one organization, a menu with several)
|
|
272
|
+
- The organization sidebar group: General (`/$slug`), Members, Teams, Billing
|
|
270
273
|
- Member invitations and roles
|
|
271
|
-
- `/organizations
|
|
272
|
-
- Sign-in still lands on `/profile`; **Manage Organizations** opens `/dashboard`
|
|
274
|
+
- `/organizations/new`, only when `VITE_ENABLE_ORG_CREATION` is also on
|
|
273
275
|
|
|
274
276
|
**When disabled:**
|
|
275
277
|
- Single-user mode only
|
|
@@ -1,37 +1,43 @@
|
|
|
1
1
|
# Organizations
|
|
2
2
|
|
|
3
|
-
Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`.
|
|
3
|
+
Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`.
|
|
4
|
+
|
|
5
|
+
- **Home** (`/home`) lists the organizations you belong to, each with **Open** (the tenant app, via `account.appUrl` and `account.tenantPattern`; see [Customization](/ui/account/customization#tenant-url-patterns)), **CMS**, and a settings gear. Pending invitations sit above the list.
|
|
6
|
+
- **The top bar** shows the organization you're in. With one organization it is a plain label. With several it is a switcher: picking an organization opens it in the app, and its gear opens its settings.
|
|
7
|
+
- **The sidebar** has a group for the current organization: **General**, **Members**, **Teams**, **Billing**.
|
|
8
|
+
|
|
9
|
+
Opening the app or the CMS for an organization makes it the session's active organization first. With exactly one organization, sessions start with it active ([Organization Defaults](/platform/auth/plugins/organization-defaults)). A pinned project (`features.pinnedOrganizationId`) shows only its configured organization and never offers another membership. Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
|
|
4
10
|
|
|
5
11
|
## Organization CRUD
|
|
6
12
|
|
|
7
|
-
- Create new organizations
|
|
8
|
-
-
|
|
13
|
+
- Create new organizations at `/organizations/new`, with `checkSlug` debounce on the slug field. Reserved slugs (`home`, `admin`, `api`, `sudo`, …) are refused with the server's reason; see [Organization Defaults](/platform/auth/plugins/organization-defaults). Only offered when the project allows self-serve creation (`plugins.organization.allowUserToCreateOrganization: true`, surfaced as `VITE_ENABLE_ORG_CREATION`). Otherwise operators create organizations from [Admin](/ui/account/features/admin)
|
|
14
|
+
- **General** (`/$slug`): update name, **slug** (rename navigates to the new URL), and **metadata** (JSON object). Members without `organization:update` see a read-only summary
|
|
9
15
|
- **Logo upload** only when `account.fileUploads: true` **and** managed R2 is configured with valid credentials (`R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`). Start apps leave this off. See [Avatars](/ui/account/features/avatars).
|
|
10
16
|
- Delete organizations — gated on the `organization:delete` permission (default: owner)
|
|
11
17
|
|
|
12
18
|
## Member Management
|
|
13
19
|
|
|
14
|
-
-
|
|
20
|
+
- **Members** (`/$slug/members`): the member list with an **Invite** button. Invite by email, with an optional team picker when teams are enabled
|
|
15
21
|
- Assign roles: **owner**, **admin**, **member**
|
|
16
22
|
- Change roles and remove members — actions are filtered per-target by the role hierarchy (non-owners can't manage owner-role members)
|
|
17
|
-
- Leave the organization
|
|
23
|
+
- Leave the organization from **General** (owners can't leave; they transfer ownership or delete)
|
|
18
24
|
|
|
19
25
|
> **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/define/access) rules — with [`auth.roleHierarchy`](/define/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above." [Custom org roles](/define/access#custom-org-roles) declared in your access trees are auto-registered with the organization plugin, so `invite-member` / `update-member-role` accept them too.
|
|
20
26
|
|
|
21
27
|
## Invitations
|
|
22
28
|
|
|
23
|
-
- Pending
|
|
29
|
+
- Pending invitations per organization, under the member list on **Members** (the old `/$slug/invitations` path redirects there)
|
|
24
30
|
- Resend, cancel (per-org), accept, and reject (per-user)
|
|
25
|
-
- Pending invites across organizations
|
|
31
|
+
- Pending invites across organizations appear on the user's Home, with Accept / Decline
|
|
26
32
|
- Invitations carry an optional `teamId` when teams are enabled — the invitee joins that team on accept
|
|
27
33
|
|
|
28
34
|
## Teams
|
|
29
35
|
|
|
30
36
|
Set `organization({ teams: { enabled: true } })` in your Better Auth config. The compiler emits `VITE_ENABLE_ORG_TEAMS=true` and the SPA exposes:
|
|
31
37
|
|
|
32
|
-
- **Teams
|
|
38
|
+
- **Teams** page on each organization, split into "Your teams" and "Other teams"
|
|
33
39
|
- **Team detail** page with member roster, add/remove members
|
|
34
|
-
- **Active-team picker**
|
|
40
|
+
- **Active-team picker** on the Teams page — switches `session.activeTeamId` via `setActiveTeam`, so server-side handlers can scope by team
|
|
35
41
|
- **Team-aware invitations** — when sending an invite, optionally pick a team; the member is added on accept
|
|
36
42
|
|
|
37
43
|
Per-team actions (create / rename / delete / add-member / remove-member) gate on the `team:create`, `team:update`, and `team:delete` permissions from Better Auth's default statements.
|
|
@@ -48,3 +54,7 @@ This means projects that ship custom roles get a UI that matches what their serv
|
|
|
48
54
|
|
|
49
55
|
- [Environment Variables](/ui/account/environment-variables)
|
|
50
56
|
- [Account UI Overview](/ui/account)
|
|
57
|
+
|
|
58
|
+
## Billing
|
|
59
|
+
|
|
60
|
+
When subscriptions are on (`VITE_ENABLE_SUBSCRIPTIONS`), each organization has a **Billing** page (`/$slug/billing`) showing its plan and subscription status. Operators manage subscriptions for every organization from **Admin → Subscriptions**.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Passkeys
|
|
2
2
|
|
|
3
|
-
When the passkey feature is enabled (`enablePasskey` on the runtime config, default: `false`), Account UI provides passkey registration and management. When
|
|
3
|
+
When the passkey feature is enabled (`enablePasskey` on the runtime config, default: `false`), Account UI provides passkey registration and management. Passkeys are managed on **Security** (`/security`); the old `/passkeys` path redirects there. When the feature is off, the Passkeys card, the Home prompt, and `/passkeys/setup` are hidden, and direct navigation redirects away.
|
|
4
4
|
|
|
5
5
|
## Passkey Registration
|
|
6
6
|
|
|
@@ -16,9 +16,13 @@ When the passkey feature is enabled (`enablePasskey` on the runtime config, defa
|
|
|
16
16
|
|
|
17
17
|
## Managing Passkeys
|
|
18
18
|
|
|
19
|
+
On **Security** (`/security`):
|
|
20
|
+
|
|
19
21
|
- View registered passkeys
|
|
20
22
|
- Remove individual passkeys
|
|
21
|
-
- Register additional passkeys
|
|
23
|
+
- Register additional passkeys, with an optional name
|
|
24
|
+
|
|
25
|
+
Home shows an **Add a passkey** prompt while you have none.
|
|
22
26
|
|
|
23
27
|
## Requirements
|
|
24
28
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Session Management
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Sessions** (`/devices`, under Account in the sidebar) lists your active sessions and lets you revoke them.
|
|
4
4
|
|
|
5
5
|
## Active Sessions
|
|
6
6
|
|
|
@@ -14,7 +14,7 @@ Users can see all devices where they're currently logged in, including:
|
|
|
14
14
|
|
|
15
15
|
Users can revoke any session except their current one. This immediately invalidates the session token.
|
|
16
16
|
|
|
17
|
-
Two events revoke other sessions without a click: changing the password
|
|
17
|
+
Two events revoke other sessions without a click: changing the password with the current password on **Security** (the UI sends `revokeOtherSessions: true`), and resetting it with an emailed code — on **Security** when email OTP is on, or through the forgot-password flow (the server default `revokeSessionsOnPasswordReset: true`, see [Session Freshness and Password Reset](/platform/auth/security#session-freshness-and-password-reset)).
|
|
18
18
|
|
|
19
19
|
## Related
|
|
20
20
|
|
|
@@ -4,25 +4,57 @@ A complete authentication and account management frontend that ships with the Qu
|
|
|
4
4
|
|
|
5
5
|
## What's Included
|
|
6
6
|
|
|
7
|
-
Account UI is a single React SPA
|
|
7
|
+
Account UI is a single React SPA. Every signed-in page renders inside one shell:
|
|
8
|
+
|
|
9
|
+
- **Top bar**: your app's name (links to Home), the organization you're in, an **Open {org} ↗** button, a **CMS** button, and the account menu.
|
|
10
|
+
- **Sidebar**: a **Home** entry, then an **Account** group, then a group for the current organization, then **Platform → Admin** for operators. On mobile the sidebar becomes a slide-out drawer.
|
|
11
|
+
|
|
12
|
+
| Sidebar entry | Path | What's there |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| **Home** | `/home` | The landing page after sign-in: pending invitations, your organizations with **Open** / **CMS** / settings buttons, and a passkey prompt when you have none |
|
|
15
|
+
| Account → **Profile** | `/profile` | Photo, name, email, and **Delete account** |
|
|
16
|
+
| Account → **Security** | `/security` | Password, passkeys, and connected (Google / Cloudflare) logins |
|
|
17
|
+
| Account → **Sessions** | `/devices` | Signed-in devices; sign out one or all |
|
|
18
|
+
| Account → **API keys** | `/api-keys` | Personal API keys (when the `apiKey` plugin is on) |
|
|
19
|
+
| *Org* → **General** | `/$slug` | Name, slug, logo, metadata; **Leave** and **Delete** |
|
|
20
|
+
| *Org* → **Members** | `/$slug/members` | Members and roles, an **Invite** button, and pending invitations |
|
|
21
|
+
| *Org* → **Teams** | `/$slug/teams` | Teams and the active-team picker (when teams are on) |
|
|
22
|
+
| *Org* → **Billing** | `/$slug/billing` | The organization's subscription (when subscriptions are on) |
|
|
23
|
+
| Platform → **Admin** | `/admin` | Users, organizations, subscriptions (operators only) |
|
|
24
|
+
|
|
25
|
+
The shell collapses with your configuration. Without organizations there is no organization switcher and no org group. With nothing to launch (no organizations, no `account.appUrl`, no CMS), Home is skipped and sign-in lands on **Profile**. Old paths redirect, so existing links keep working: `/dashboard` → `/home`, `/passkeys` and `/connected-accounts` → `/security`, `/$slug/settings` → `/$slug`, `/$slug/invitations` → `/$slug/members`.
|
|
8
26
|
|
|
9
|
-
|
|
27
|
+
Served on its own domain (e.g., `auth.example.com`) or at `/account/` when embedded alongside the CMS.
|
|
10
28
|
|
|
11
|
-
|
|
29
|
+
### Getting into the app
|
|
12
30
|
|
|
13
|
-
|
|
31
|
+
There is one rule for every **Open** button: the organization's tenant URL (`account.appUrl` plus `account.tenantPattern` with the slug substituted), else the plain `account.appUrl`, else no button. Opening the app for an organization first makes it the session's active organization, the same way the CMS launch does, so the app never opens into an organization left active by an earlier visit.
|
|
14
32
|
|
|
15
|
-
|
|
33
|
+
Accepting an invitation opens the app for that organization when the project has an app URL. Otherwise it goes to Home.
|
|
16
34
|
|
|
17
|
-
|
|
35
|
+
### Organizations
|
|
36
|
+
|
|
37
|
+
How the organization switcher in the top bar behaves depends on how many organizations you belong to:
|
|
38
|
+
|
|
39
|
+
| Organizations | Top bar | Home |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| 0 | No switcher | Pending invitations and an empty state. **Open** goes to the plain `account.appUrl` when set. |
|
|
42
|
+
| 1 | The org's name as a plain label (no menu) | One large **Open {org}** button, plus **Open CMS** and settings |
|
|
43
|
+
| 2+ | A menu. Picking an org opens it in the app; the gear opens its settings. | One row per org with **Open**, **CMS**, and settings |
|
|
44
|
+
|
|
45
|
+
With exactly one organization, the session starts with it active, so the app, the CMS, and org-scoped API calls default to it. The server does this when the session is created ([Organization Defaults](/platform/auth/plugins/organization-defaults)), and Account UI repeats it for older sessions. Neither overrides an organization that is already active. When `features.pinnedOrganizationId` is set, the shell shows only that organization, so it always behaves as a single-organization account.
|
|
46
|
+
|
|
47
|
+
Some slugs are reserved (`home`, `admin`, `api`, `sudo`, …) because they would shadow a route; the slug field says so as you type. See [Organization Defaults](/platform/auth/plugins/organization-defaults#reserved-organization-slugs).
|
|
48
|
+
|
|
49
|
+
**New organization** appears (on Home and in the switcher) only when the project allows self-serve creation with `plugins.organization.allowUserToCreateOrganization: true`. By default the server closes `POST /organization/create`, and operators create organizations from **Admin → Organizations** instead. See [Admin](/ui/account/features/admin).
|
|
18
50
|
|
|
19
|
-
###
|
|
51
|
+
### CMS launch
|
|
20
52
|
|
|
21
|
-
|
|
53
|
+
When the project also enables the CMS, the top bar and Home have a CMS action. It opens the current organization's CMS directly. Otherwise, one membership opens that organization and several memberships produce a picker. Account UI makes the selected organization active before navigating, so the CMS cannot inherit a different active organization from an earlier session. The action follows `cms.access`: membership is required in `"member"` mode, while only `user.role === "sysadmin"` sees it in `"sysadmin"` mode. A zero-membership sysadmin opens the tenant picker only when `cms.sysadmin: true` explicitly enables cross-tenant scope. When `features.pinnedOrganizationId` is set, the action targets only that fixed organization and never offers the caller's other memberships.
|
|
22
54
|
|
|
23
|
-
### Admin Panel (
|
|
55
|
+
### Admin Panel (operators only)
|
|
24
56
|
|
|
25
|
-
User management
|
|
57
|
+
User management: view all users, search, create accounts, ban/unban, reset passwords, manage sessions, and create organizations with a named owner. It is visible to operator roles (`appmanager`, `sysadmin`) when `auth.admin` is on, and renders inside the same shell. Can be served on its own domain (e.g., `admin.example.com`) via the `adminDomain` config.
|
|
26
58
|
|
|
27
59
|
## How to Enable
|
|
28
60
|
|
|
@@ -54,24 +86,23 @@ npx wrangler deploy
|
|
|
54
86
|
|
|
55
87
|
That's it. The compiler:
|
|
56
88
|
1. Reads your auth feature flags and branding from the config
|
|
57
|
-
2.
|
|
58
|
-
3.
|
|
59
|
-
4.
|
|
60
|
-
5. Bundles the built assets into your Worker alongside the API
|
|
89
|
+
2. Copies the generic prebuilt Account bundle (built once, when the compiler image is built) into `src/apps/account/`
|
|
90
|
+
3. Emits the per-project values (feature flags, URLs, branding) that the Worker injects into every served page as `window.__QUICKBACK_RUNTIME`
|
|
91
|
+
4. Serves the assets from your Worker alongside the API
|
|
61
92
|
|
|
62
|
-
No manual `.env` configuration needed. No separate deployment.
|
|
93
|
+
Compiles never run Vite. No manual `.env` configuration needed. No separate deployment.
|
|
63
94
|
|
|
64
95
|
See [Configuration](/configure) for all `account` options and [Multi-Domain Architecture](/configure/domains) for custom domain setup.
|
|
65
96
|
|
|
66
|
-
### Skip
|
|
97
|
+
### Skip Staging the Account Assets
|
|
67
98
|
|
|
68
|
-
After the first compile, skip
|
|
99
|
+
After the first compile, skip copying the Account assets on subsequent compiles:
|
|
69
100
|
|
|
70
101
|
```typescript
|
|
71
102
|
account: { build: false, /* ...other options */ }
|
|
72
103
|
```
|
|
73
104
|
|
|
74
|
-
|
|
105
|
+
Use it while iterating on API features. Set it back to `true` (or omit it) to pick up a newer Account bundle.
|
|
75
106
|
|
|
76
107
|
### Custom Output Directory
|
|
77
108
|
|
|
@@ -81,28 +112,28 @@ account: { outputDir: "my-custom-path/account" }
|
|
|
81
112
|
|
|
82
113
|
Changes where compiled Account assets are placed, instead of the default `src/apps/account/`.
|
|
83
114
|
|
|
84
|
-
##
|
|
115
|
+
## Feature Gating
|
|
85
116
|
|
|
86
|
-
Auth feature flags control which pages
|
|
117
|
+
Auth feature flags control which pages and controls exist:
|
|
87
118
|
|
|
88
119
|
| Flag | Pages Included |
|
|
89
120
|
|------|---------------|
|
|
90
|
-
| `auth.password` | Password login
|
|
91
|
-
| `auth.emailOTP` | Email OTP login flow, email-based password reset |
|
|
92
|
-
| `auth.passkey` |
|
|
93
|
-
| `auth.organizations` |
|
|
94
|
-
| `auth.admin` | Admin panel (user management) |
|
|
121
|
+
| `auth.password` | Password login; **Change password** on Security |
|
|
122
|
+
| `auth.emailOTP` | Email OTP login flow, email-based password reset; on Security, password changes are confirmed with an emailed code |
|
|
123
|
+
| `auth.passkey` | Passkeys on Security, the `/passkeys/setup` prompt, the passkey nudge on Home |
|
|
124
|
+
| `auth.organizations` | The organization switcher, org cards and invitations on Home, the org sidebar group (General, Members, Teams, Billing) |
|
|
125
|
+
| `auth.admin` | Admin panel (user and organization management) |
|
|
95
126
|
|
|
96
|
-
When a flag is `false`, the corresponding routes **guard themselves at runtime** — each feature route checks its flag from the worker-injected `window.__QUICKBACK_RUNTIME` config in `beforeLoad` and redirects away, and
|
|
127
|
+
When a flag is `false`, the corresponding routes **guard themselves at runtime** — each feature route checks its flag from the worker-injected `window.__QUICKBACK_RUNTIME` config in `beforeLoad` and redirects away, and its sidebar entries and buttons are hidden. The Account SPA ships as one generic prebuilt bundle; flags decide which surfaces exist for your project.
|
|
97
128
|
|
|
98
129
|
## Features
|
|
99
130
|
|
|
100
131
|
- **Authentication** — Email/password, passkeys (WebAuthn), email OTP, email verification, password reset, and the confirm page that magic-link emails open (`/magic-link`)
|
|
101
|
-
- **Account Management** — Profile editing, avatar upload, password changes,
|
|
102
|
-
- **Connected Accounts** — Link Google and Cloudflare logins
|
|
103
|
-
- **Organizations** — Multi-tenant org management with owner/admin/member roles, invitations, and org settings
|
|
132
|
+
- **Account Management** — Profile editing, avatar upload, password changes, session management, account deletion
|
|
133
|
+
- **Connected Accounts** — Link Google and Cloudflare logins on `/security`
|
|
134
|
+
- **Organizations** — Multi-tenant org management with owner/admin/member roles, invitations, teams, billing, and org settings
|
|
104
135
|
- **Admin Panel** — User management dashboard with search, create, ban/unban, password reset, and session viewing
|
|
105
|
-
- **API Keys** — Generate and manage API keys from `/api-keys`
|
|
136
|
+
- **API Keys** — Generate and manage API keys from `/api-keys`
|
|
106
137
|
- **CLI Authorization** — Device authorization flow for `quickback login`
|
|
107
138
|
|
|
108
139
|
## Next Steps
|
|
@@ -68,7 +68,7 @@ auth: {
|
|
|
68
68
|
password: true, // Email/password login + inline password change
|
|
69
69
|
emailOTP: false, // Email OTP login flow
|
|
70
70
|
passkey: true, // WebAuthn passkey setup + management
|
|
71
|
-
organizations: true, //
|
|
71
|
+
organizations: true, // org switcher, Home org list + invitations, org settings
|
|
72
72
|
admin: true, // Admin panel (user management)
|
|
73
73
|
}
|
|
74
74
|
```
|
|
@@ -138,7 +138,7 @@ This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `
|
|
|
138
138
|
|
|
139
139
|
CMS access defaults to `access: "sysadmin"` — only `user.role === "sysadmin"` (the cross-tenant data-plane tier) can use `/cms/*`. Set `access: "member"` to also admit anyone holding an organization membership. `user.role === "appmanager"` opens the CMS in neither mode: it is the control-plane tier and belongs at `/account/admin`. The gate is enforced at multiple layers:
|
|
140
140
|
|
|
141
|
-
- **Account UI** hides
|
|
141
|
+
- **Account UI** hides its **CMS** button for callers outside those roles.
|
|
142
142
|
- **CMS SPA shell** — the Worker redirects unauthenticated requests to login. Sign-in is the only shell-level gate; the app itself is a generic bundle. For a caller `/api/v1/schema` would admit, the Worker also inlines the schema registry in the shell as a non-executing `<script type="application/json" id="__qb-cms-bootstrap">` block, so the CMS starts without fetching it. The block uses the same admission check as `/api/v1/schema`, so it never carries anything that route would refuse. With [Cloudflare Access](/configure/cloudflare-access), it is inlined only when `/api/v1/schema` needs no Access application or the same one the shell request passed. The CMS shell is served `Cache-Control: private, no-store`.
|
|
143
143
|
- **`/api/v1/schema`** returns `401 AUTH_MISSING` to anonymous callers `403 CMS_ACCESS_DENIED` (naming the role required) to signed-in callers outside those roles, and `403 MFA_REQUIRED` to an operator whose session lacks the second factor `auth.operatorMfa` demands, so schema metadata can't be scraped by hitting the API directly.
|
|
144
144
|
- **`custom_view` routes** are gated on `userRole: ["appmanager"]` rather than org membership, so saved views can't be listed or modified without platform-control-plane rights.
|
|
@@ -181,7 +181,7 @@ Start apps ship that setting. A sysadmin who also holds an organization membersh
|
|
|
181
181
|
> **File uploads need valid R2 credentials**
|
|
182
182
|
>
|
|
183
183
|
> Profile pictures and organization logos are **Account UI**, not the CMS — they
|
|
184
|
-
> live at `/account/profile` and `/account/<slug
|
|
184
|
+
> live at `/account/profile` and `/account/<slug>` (the organization's General page). They only work with
|
|
185
185
|
> `account.fileUploads: true`, [managed R2](/platform/storage/r2)
|
|
186
186
|
> (`defineFileStorage("cloudflare-r2", { managed: true })`), and the
|
|
187
187
|
> `R2_ACCOUNT_ID` / `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` secrets. A
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.72.
|
|
3
|
+
"version": "0.72.9",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -172,7 +172,7 @@ When the compiler builds the Account SPA, it excludes route files for disabled f
|
|
|
172
172
|
|
|
173
173
|
| Feature Flag | Routes Excluded When `false` |
|
|
174
174
|
|-------------|------------------------------|
|
|
175
|
-
| `auth.organizations` |
|
|
175
|
+
| `auth.organizations` | Org switcher, Home org list + invitations, org pages (`/$slug`: General, Members, Teams, Billing) |
|
|
176
176
|
| `auth.passkey` | Passkey management and setup |
|
|
177
177
|
| `auth.admin` | Admin panel routes |
|
|
178
178
|
|
|
@@ -699,7 +699,7 @@ account: {
|
|
|
699
699
|
|--------|------|-------------|
|
|
700
700
|
| `domain` | `string` | Custom domain for Account UI (e.g., `auth.example.com`) |
|
|
701
701
|
| `adminDomain` | `string` | Custom domain for admin-only access (e.g., `admin.example.com`). Serves the same Account SPA — the client-side router handles admin routing. |
|
|
702
|
-
| `appUrl` | `string` | Origin of the tenant's main application. Baked into the Account SPA as `VITE_QUICKBACK_APP_URL`. Combined with `tenantPattern` for
|
|
702
|
+
| `appUrl` | `string` | Origin of the tenant's main application. Baked into the Account SPA as `VITE_QUICKBACK_APP_URL`. Combined with `tenantPattern` for every **Open** button (top bar, Home, org switcher). Independent from `domain`. A deploy-target `APP_URL` can override this at serve time. |
|
|
703
703
|
| `tenantPattern` | `string` | URL pattern for a tenant, with `{slug}` substituted. Default `/{slug}`. Relative patterns are resolved against `appUrl`; a full `https://{slug}.example.com` pattern is used as-is. Baked as `VITE_TENANT_URL_PATTERN`. |
|
|
704
704
|
| `name` | `string` | App display name shown on login, profile, and email templates |
|
|
705
705
|
| `companyName` | `string` | Company name for branding |
|
|
@@ -718,7 +718,7 @@ Control which authentication features are exposed. Disabled features are hidden
|
|
|
718
718
|
| `auth.emailOTP` | `boolean` | `false` | adds `emailOtp` plugin | Email one-time password login — adds plugin server-side, surfaces UI |
|
|
719
719
|
| `auth.passkey` | `boolean` | `false` | adds `passkey` plugin | WebAuthn/FIDO2 passkey authentication — adds plugin server-side, surfaces UI |
|
|
720
720
|
| `auth.signup` | `boolean` | `true` | `signup.inviteOnly` (inverted) | Self-service account registration — false hides open signup in the UI **and** makes the server [invite-only](/platform/auth/security#signup-policy): every sign-in method refuses new accounts with 403 `SIGNUP_NOT_ALLOWED` unless the email holds a pending invitation |
|
|
721
|
-
| `auth.organizations` | `boolean` | `true` | UI surface only | Organization
|
|
721
|
+
| `auth.organizations` | `boolean` | `true` | UI surface only | Organization UI: the switcher, the org list and invitations on Home, and the org pages. Sign-in lands on `/home`. Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
|
|
722
722
|
| `auth.admin` | `boolean` | `false` | UI surface only | Admin panel for user management in the Account SPA. The Better Auth admin plugin is compiler-managed separately from this UI toggle |
|
|
723
723
|
| `auth.emailVerification` | `boolean` | `false` | `emailAndPassword.requireEmailVerification` | Require email verification before sessions are issued. False = sessions usable immediately after signup |
|
|
724
724
|
|
|
@@ -94,6 +94,7 @@ When `features.pinnedOrganizationId` is set:
|
|
|
94
94
|
- the CMS skips the org-selection gate
|
|
95
95
|
- API calls and realtime connections use the pinned org automatically
|
|
96
96
|
- role checks still come from the caller's membership in that org
|
|
97
|
+
- a member's new sessions start with the pinned org active ([Organization Defaults](/platform/auth/plugins/organization-defaults))
|
|
97
98
|
|
|
98
99
|
This is the intended replacement for the old single-tenant CMS flow.
|
|
99
100
|
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Organization Defaults
|
|
2
|
+
|
|
3
|
+
Every Better Auth project ships `organizationDefaults()`, a Better Auth plugin the compiler emits into `src/plugins/organization-defaults/` and adds to `src/lib/auth.ts` alongside `organization()`. It needs no configuration.
|
|
4
|
+
|
|
5
|
+
## Reserved organization slugs
|
|
6
|
+
|
|
7
|
+
An organization slug becomes a URL segment: `/account/<slug>` in the Account UI, and `<appUrl>/<slug>` in your app with the default `tenantPattern`. A slug that matches a route shadows it. An organization called `security` could never open its own page, and one called `admin` or `support` impersonates something it isn't.
|
|
8
|
+
|
|
9
|
+
The plugin refuses about 150 reserved slugs with `400` and `code: "ORGANIZATION_SLUG_RESERVED"` on:
|
|
10
|
+
|
|
11
|
+
- `POST /auth/v1/organization/create`
|
|
12
|
+
- `POST /auth/v1/organization/update` (renaming the slug)
|
|
13
|
+
- `POST /auth/v1/organization/check-slug`, so the Account UI's "is this URL available" check agrees with the write
|
|
14
|
+
- the operator route `POST /auth/v1/admin/create-organization`, which writes the row directly and applies the same rule
|
|
15
|
+
|
|
16
|
+
Matching is exact and case-insensitive: `home` is reserved, `home-depot` is not. The list covers:
|
|
17
|
+
|
|
18
|
+
- every top-level Account UI route (`home`, `profile`, `security`, `dashboard`, `login`, …)
|
|
19
|
+
- auth and account words (`settings`, `billing`, `members`, `invite`, `oauth`, …)
|
|
20
|
+
- platform paths (`api`, `cms`, `app`, `static`, `webhooks`, `www`, …)
|
|
21
|
+
- roles and system accounts (`admin`, `root`, `sysadmin`, `superuser`, `system`, …)
|
|
22
|
+
- common shell commands (`sudo`, `ls`, `rm`, `cd`, `git`, `curl`, …)
|
|
23
|
+
- values that read as code (`null`, `undefined`, `true`, `localhost`, `env`, …)
|
|
24
|
+
|
|
25
|
+
The full list is `RESERVED_ORGANIZATION_SLUGS` in `src/plugins/organization-defaults/reserved-slugs.ts`. A compiler test fails if a new top-level Account UI route is missing from it.
|
|
26
|
+
|
|
27
|
+
Organizations that already hold a reserved slug keep it. Updates that don't change the slug still work, but the org's Account page is shadowed by the route until it is renamed.
|
|
28
|
+
|
|
29
|
+
## Default active organization
|
|
30
|
+
|
|
31
|
+
New sessions start with no active organization, so the app, the CMS, and org-scoped API calls have nothing to default to. The plugin fills that gap when the choice is unambiguous:
|
|
32
|
+
|
|
33
|
+
- **Pinned project** (`features.pinnedOrganizationId`): a member of the pinned organization starts every session in it.
|
|
34
|
+
- **One membership**: the session starts in that organization.
|
|
35
|
+
- **Several memberships, or none**: nothing is chosen; the user picks an organization in the app or the Account UI.
|
|
36
|
+
|
|
37
|
+
It never overrides an active organization the session already carries. The Account UI applies the same rule client-side for sessions created before the plugin existed.
|
|
@@ -89,6 +89,8 @@ When organizations are enabled, the active organization is on the auth context a
|
|
|
89
89
|
const orgId = c.get('ctx').activeOrgId;
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
+
A new session starts in the user's organization when the choice is unambiguous (the pinned organization, or their only membership). With several memberships, `activeOrgId` stays unset until the user picks one. See [Organization Defaults](/platform/auth/plugins/organization-defaults).
|
|
93
|
+
|
|
92
94
|
> **`activeOrgId`, not `activeOrganizationId`**
|
|
93
95
|
>
|
|
94
96
|
> `activeOrganizationId` is Better Auth's *session* field name (`session.session.activeOrganizationId`). Quickback canonicalises it to `ctx.activeOrgId`; firewall rules written against `ctx.activeOrganizationId` are rewritten to `ctx.activeOrgId` at compile time.
|
|
@@ -93,7 +93,7 @@ setAppConfig({
|
|
|
93
93
|
| `privacy` | "Privacy Policy" | Footer link text |
|
|
94
94
|
| `support` | "Contact Support" | Footer link text |
|
|
95
95
|
| `company` | (from `VITE_COMPANY_NAME`) | Footer company name |
|
|
96
|
-
| `organizations` | "Organizations" | Navigation and
|
|
96
|
+
| `organizations` | "Organizations" | Navigation, the switcher, and Home. The singular form (trailing `s` dropped) labels **New …** and **… settings**, so `"Workspaces"` gives **New workspace**. |
|
|
97
97
|
|
|
98
98
|
## Custom Messages
|
|
99
99
|
|
|
@@ -153,7 +153,7 @@ setAppConfig({
|
|
|
153
153
|
welcome: '/getting-started',
|
|
154
154
|
},
|
|
155
155
|
authenticated: {
|
|
156
|
-
|
|
156
|
+
home: '/home',
|
|
157
157
|
profile: '/my-account',
|
|
158
158
|
settings: '/preferences',
|
|
159
159
|
},
|
|
@@ -149,6 +149,7 @@ Enable or disable features using boolean environment variables. **Every flag car
|
|
|
149
149
|
|---|---|---|
|
|
150
150
|
| `VITE_ENABLE_ORGANIZATIONS` | `organizations` | `false` |
|
|
151
151
|
| `VITE_ENABLE_ORG_TEAMS` | `orgTeams` | `false` |
|
|
152
|
+
| `VITE_ENABLE_ORG_CREATION` | `orgCreation` | `false` |
|
|
152
153
|
| `VITE_ENABLE_ADMIN` | `admin` | `false` |
|
|
153
154
|
| `VITE_ENABLE_FILE_UPLOADS` | `fileUploads` | `false` |
|
|
154
155
|
| `VITE_ENABLE_PASSKEY` | `passkey` | `false` |
|
|
@@ -193,7 +194,12 @@ VITE_ENABLE_REALTIME=false # default: false
|
|
|
193
194
|
VITE_ENABLE_ORGANIZATIONS=false # default: false
|
|
194
195
|
VITE_ENABLE_ORG_TEAMS=false # default: false
|
|
195
196
|
# Auto-set to true when the BA config has organization({ teams: { enabled: true } }).
|
|
196
|
-
# When false the Teams
|
|
197
|
+
# When false the Teams page is hidden and the auth client doesn't expose team APIs.
|
|
198
|
+
VITE_ENABLE_ORG_CREATION=false # default: false
|
|
199
|
+
# Auto-set to true when the BA config sets
|
|
200
|
+
# plugins.organization.allowUserToCreateOrganization: true. When false there is no
|
|
201
|
+
# "New organization" button and /organizations/new redirects home (the server
|
|
202
|
+
# closes POST /organization/create; operators create orgs from Admin).
|
|
197
203
|
|
|
198
204
|
# Admin
|
|
199
205
|
VITE_ENABLE_ADMIN=false # default: false — the compiler always emits it explicitly
|
|
@@ -72,7 +72,7 @@ curl -X POST https://api.example.com/auth/v1/admin/set-role \
|
|
|
72
72
|
|
|
73
73
|
Better Auth's `organization.create` seats whoever calls it. For an operator that is an escalation rather than a convenience: the membership it grants is tenant-data access — under `cms.access: "member"`, access to that organization's records — which is exactly what the `appmanager`/`sysadmin` split withholds.
|
|
74
74
|
|
|
75
|
-
So organization creation asks for an `ownerUserId`, seats that user, and never seats the caller. Self-serve creation (`POST /auth/v1/organization/create`) is closed by default for the same reason; a project that wants it sets `plugins.organization.allowUserToCreateOrganization: true`.
|
|
75
|
+
So organization creation asks for an `ownerUserId`, seats that user, and never seats the caller. Self-serve creation (`POST /auth/v1/organization/create`) is closed by default for the same reason; a project that wants it sets `plugins.organization.allowUserToCreateOrganization: true`. Account UI follows the same setting: it shows **New organization** (and serves `/organizations/new`) only when that option is `true`. Both routes refuse [reserved slugs](/platform/auth/plugins/organization-defaults#reserved-organization-slugs).
|
|
76
76
|
|
|
77
77
|
An operator who genuinely wants their own organization creates one naming themselves as owner — explicit, and visible in the audit trail rather than implied by whoever happened to make the call.
|
|
78
78
|
|
|
@@ -127,7 +127,7 @@ The admin domain serves the same Account SPA at root (`/`). The SPA's client-sid
|
|
|
127
127
|
|
|
128
128
|
## CMS Access Control
|
|
129
129
|
|
|
130
|
-
When both CMS and Account UI are enabled, the Account
|
|
130
|
+
When both CMS and Account UI are enabled, the Account top bar and Home show a CMS action. It opens the current (or sole) organization directly, or lets a multi-organization user choose one first. You can restrict this to the sysadmin tier only:
|
|
131
131
|
|
|
132
132
|
```typescript
|
|
133
133
|
cms: { domain: "cms.example.com", access: "sysadmin" },
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# API Key Management
|
|
2
2
|
|
|
3
|
-
API keys are a user credential. Manage them at `/api-keys
|
|
3
|
+
API keys are a user credential. Manage them at `/api-keys` (**API keys** under Account in the sidebar). The `apiKey` plugin is on by default.
|
|
4
4
|
|
|
5
5
|
## Creating API Keys
|
|
6
6
|
|
|
@@ -11,18 +11,20 @@ Control which features are available in your Account UI deployment using feature
|
|
|
11
11
|
|
|
12
12
|
### `appConfig.features`
|
|
13
13
|
|
|
14
|
-
These
|
|
14
|
+
These thirteen flags populate `appConfig.features` and are the ones `isFeatureEnabled()` accepts.
|
|
15
15
|
|
|
16
16
|
| Variable | `features` key | Default |
|
|
17
17
|
|---|---|---|
|
|
18
18
|
| `VITE_ENABLE_ORGANIZATIONS` | `organizations` | `false` |
|
|
19
19
|
| `VITE_ENABLE_ORG_TEAMS` | `orgTeams` | `false` |
|
|
20
|
+
| `VITE_ENABLE_ORG_CREATION` | `orgCreation` | `false` |
|
|
20
21
|
| `VITE_ENABLE_ADMIN` | `admin` | `false` |
|
|
21
22
|
| `VITE_ENABLE_FILE_UPLOADS` | `fileUploads` | `false` |
|
|
22
23
|
| `VITE_ENABLE_PASSKEY` | `passkey` | `false` |
|
|
23
24
|
| `VITE_ENABLE_EMAIL_OTP` | `emailOTP` | `false` |
|
|
24
25
|
| `VITE_ENABLE_PASSWORD` | `password` | `true` |
|
|
25
26
|
| `VITE_ENABLE_GOOGLE_OAUTH` | `googleOAuth` | `false` |
|
|
27
|
+
| `VITE_ENABLE_CLOUDFLARE_OAUTH` | `cloudflareOAuth` | `false` |
|
|
26
28
|
| `VITE_ENABLE_SUBSCRIPTIONS` | `subscriptions` | `false` |
|
|
27
29
|
| `VITE_ENABLE_REALTIME` | `realtime` | `false` |
|
|
28
30
|
| `VITE_ENABLE_API_KEYS` | `apiKeys` | `true` |
|
|
@@ -176,10 +178,10 @@ VITE_ENABLE_GOOGLE_OAUTH=false # default: false
|
|
|
176
178
|
|
|
177
179
|
**When enabled:**
|
|
178
180
|
- "Continue with Google" button on the login and signup pages
|
|
179
|
-
- Google row
|
|
181
|
+
- Google row under **Connected accounts** on `/security`
|
|
180
182
|
|
|
181
183
|
**When disabled:**
|
|
182
|
-
- No social sign-in button
|
|
184
|
+
- No social sign-in button and no **Connected accounts** card on `/security`
|
|
183
185
|
|
|
184
186
|
**Requirements:**
|
|
185
187
|
- Google OAuth credentials configured on the Better Auth side
|
|
@@ -192,7 +194,7 @@ VITE_ENABLE_CLOUDFLARE_OAUTH=false # default: false
|
|
|
192
194
|
|
|
193
195
|
**When enabled:**
|
|
194
196
|
- "Continue with Cloudflare" button on the login and signup pages
|
|
195
|
-
- Cloudflare rows on `/
|
|
197
|
+
- Cloudflare rows under **Connected accounts** on `/security` — unlike
|
|
196
198
|
Google, more than one Cloudflare identity can be linked to the same user
|
|
197
199
|
(**Connect another Cloudflare account**), and every linked identity signs
|
|
198
200
|
in to this user. Link work and personal Cloudflare logins here so each one
|
|
@@ -265,11 +267,11 @@ VITE_ENABLE_ORGANIZATIONS=false # default: false
|
|
|
265
267
|
```
|
|
266
268
|
|
|
267
269
|
**When enabled:**
|
|
268
|
-
- `/
|
|
269
|
-
-
|
|
270
|
+
- Home (`/home`) lists your organizations, each with **Open** / **CMS** / settings, plus pending invitations
|
|
271
|
+
- The organization switcher in the top bar (a plain label with one organization, a menu with several)
|
|
272
|
+
- The organization sidebar group: General (`/$slug`), Members, Teams, Billing
|
|
270
273
|
- Member invitations and roles
|
|
271
|
-
- `/organizations
|
|
272
|
-
- Sign-in still lands on `/profile`; **Manage Organizations** opens `/dashboard`
|
|
274
|
+
- `/organizations/new`, only when `VITE_ENABLE_ORG_CREATION` is also on
|
|
273
275
|
|
|
274
276
|
**When disabled:**
|
|
275
277
|
- Single-user mode only
|
|
@@ -1,37 +1,43 @@
|
|
|
1
1
|
# Organizations
|
|
2
2
|
|
|
3
|
-
Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`.
|
|
3
|
+
Account UI provides a complete organization management interface when `VITE_ENABLE_ORGANIZATIONS=true`.
|
|
4
|
+
|
|
5
|
+
- **Home** (`/home`) lists the organizations you belong to, each with **Open** (the tenant app, via `account.appUrl` and `account.tenantPattern`; see [Customization](/ui/account/customization#tenant-url-patterns)), **CMS**, and a settings gear. Pending invitations sit above the list.
|
|
6
|
+
- **The top bar** shows the organization you're in. With one organization it is a plain label. With several it is a switcher: picking an organization opens it in the app, and its gear opens its settings.
|
|
7
|
+
- **The sidebar** has a group for the current organization: **General**, **Members**, **Teams**, **Billing**.
|
|
8
|
+
|
|
9
|
+
Opening the app or the CMS for an organization makes it the session's active organization first. With exactly one organization, sessions start with it active ([Organization Defaults](/platform/auth/plugins/organization-defaults)). A pinned project (`features.pinnedOrganizationId`) shows only its configured organization and never offers another membership. Teams are a separate opt-in (`VITE_ENABLE_ORG_TEAMS`), surfaced when the compiler detects `organization({ teams: { enabled: true } })` in the Better Auth config.
|
|
4
10
|
|
|
5
11
|
## Organization CRUD
|
|
6
12
|
|
|
7
|
-
- Create new organizations
|
|
8
|
-
-
|
|
13
|
+
- Create new organizations at `/organizations/new`, with `checkSlug` debounce on the slug field. Reserved slugs (`home`, `admin`, `api`, `sudo`, …) are refused with the server's reason; see [Organization Defaults](/platform/auth/plugins/organization-defaults). Only offered when the project allows self-serve creation (`plugins.organization.allowUserToCreateOrganization: true`, surfaced as `VITE_ENABLE_ORG_CREATION`). Otherwise operators create organizations from [Admin](/ui/account/features/admin)
|
|
14
|
+
- **General** (`/$slug`): update name, **slug** (rename navigates to the new URL), and **metadata** (JSON object). Members without `organization:update` see a read-only summary
|
|
9
15
|
- **Logo upload** only when `account.fileUploads: true` **and** managed R2 is configured with valid credentials (`R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`). Start apps leave this off. See [Avatars](/ui/account/features/avatars).
|
|
10
16
|
- Delete organizations — gated on the `organization:delete` permission (default: owner)
|
|
11
17
|
|
|
12
18
|
## Member Management
|
|
13
19
|
|
|
14
|
-
-
|
|
20
|
+
- **Members** (`/$slug/members`): the member list with an **Invite** button. Invite by email, with an optional team picker when teams are enabled
|
|
15
21
|
- Assign roles: **owner**, **admin**, **member**
|
|
16
22
|
- Change roles and remove members — actions are filtered per-target by the role hierarchy (non-owners can't manage owner-role members)
|
|
17
|
-
- Leave the organization
|
|
23
|
+
- Leave the organization from **General** (owners can't leave; they transfer ownership or delete)
|
|
18
24
|
|
|
19
25
|
> **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/define/access) rules — with [`auth.roleHierarchy`](/define/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above." [Custom org roles](/define/access#custom-org-roles) declared in your access trees are auto-registered with the organization plugin, so `invite-member` / `update-member-role` accept them too.
|
|
20
26
|
|
|
21
27
|
## Invitations
|
|
22
28
|
|
|
23
|
-
- Pending
|
|
29
|
+
- Pending invitations per organization, under the member list on **Members** (the old `/$slug/invitations` path redirects there)
|
|
24
30
|
- Resend, cancel (per-org), accept, and reject (per-user)
|
|
25
|
-
- Pending invites across organizations
|
|
31
|
+
- Pending invites across organizations appear on the user's Home, with Accept / Decline
|
|
26
32
|
- Invitations carry an optional `teamId` when teams are enabled — the invitee joins that team on accept
|
|
27
33
|
|
|
28
34
|
## Teams
|
|
29
35
|
|
|
30
36
|
Set `organization({ teams: { enabled: true } })` in your Better Auth config. The compiler emits `VITE_ENABLE_ORG_TEAMS=true` and the SPA exposes:
|
|
31
37
|
|
|
32
|
-
- **Teams
|
|
38
|
+
- **Teams** page on each organization, split into "Your teams" and "Other teams"
|
|
33
39
|
- **Team detail** page with member roster, add/remove members
|
|
34
|
-
- **Active-team picker**
|
|
40
|
+
- **Active-team picker** on the Teams page — switches `session.activeTeamId` via `setActiveTeam`, so server-side handlers can scope by team
|
|
35
41
|
- **Team-aware invitations** — when sending an invite, optionally pick a team; the member is added on accept
|
|
36
42
|
|
|
37
43
|
Per-team actions (create / rename / delete / add-member / remove-member) gate on the `team:create`, `team:update`, and `team:delete` permissions from Better Auth's default statements.
|
|
@@ -48,3 +54,7 @@ This means projects that ship custom roles get a UI that matches what their serv
|
|
|
48
54
|
|
|
49
55
|
- [Environment Variables](/ui/account/environment-variables)
|
|
50
56
|
- [Account UI Overview](/ui/account)
|
|
57
|
+
|
|
58
|
+
## Billing
|
|
59
|
+
|
|
60
|
+
When subscriptions are on (`VITE_ENABLE_SUBSCRIPTIONS`), each organization has a **Billing** page (`/$slug/billing`) showing its plan and subscription status. Operators manage subscriptions for every organization from **Admin → Subscriptions**.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Passkeys
|
|
2
2
|
|
|
3
|
-
When the passkey feature is enabled (`enablePasskey` on the runtime config, default: `false`), Account UI provides passkey registration and management. When
|
|
3
|
+
When the passkey feature is enabled (`enablePasskey` on the runtime config, default: `false`), Account UI provides passkey registration and management. Passkeys are managed on **Security** (`/security`); the old `/passkeys` path redirects there. When the feature is off, the Passkeys card, the Home prompt, and `/passkeys/setup` are hidden, and direct navigation redirects away.
|
|
4
4
|
|
|
5
5
|
## Passkey Registration
|
|
6
6
|
|
|
@@ -16,9 +16,13 @@ When the passkey feature is enabled (`enablePasskey` on the runtime config, defa
|
|
|
16
16
|
|
|
17
17
|
## Managing Passkeys
|
|
18
18
|
|
|
19
|
+
On **Security** (`/security`):
|
|
20
|
+
|
|
19
21
|
- View registered passkeys
|
|
20
22
|
- Remove individual passkeys
|
|
21
|
-
- Register additional passkeys
|
|
23
|
+
- Register additional passkeys, with an optional name
|
|
24
|
+
|
|
25
|
+
Home shows an **Add a passkey** prompt while you have none.
|
|
22
26
|
|
|
23
27
|
## Requirements
|
|
24
28
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Session Management
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Sessions** (`/devices`, under Account in the sidebar) lists your active sessions and lets you revoke them.
|
|
4
4
|
|
|
5
5
|
## Active Sessions
|
|
6
6
|
|
|
@@ -14,7 +14,7 @@ Users can see all devices where they're currently logged in, including:
|
|
|
14
14
|
|
|
15
15
|
Users can revoke any session except their current one. This immediately invalidates the session token.
|
|
16
16
|
|
|
17
|
-
Two events revoke other sessions without a click: changing the password
|
|
17
|
+
Two events revoke other sessions without a click: changing the password with the current password on **Security** (the UI sends `revokeOtherSessions: true`), and resetting it with an emailed code — on **Security** when email OTP is on, or through the forgot-password flow (the server default `revokeSessionsOnPasswordReset: true`, see [Session Freshness and Password Reset](/platform/auth/security#session-freshness-and-password-reset)).
|
|
18
18
|
|
|
19
19
|
## Related
|
|
20
20
|
|
|
@@ -4,25 +4,57 @@ A complete authentication and account management frontend that ships with the Qu
|
|
|
4
4
|
|
|
5
5
|
## What's Included
|
|
6
6
|
|
|
7
|
-
Account UI is a single React SPA
|
|
7
|
+
Account UI is a single React SPA. Every signed-in page renders inside one shell:
|
|
8
|
+
|
|
9
|
+
- **Top bar**: your app's name (links to Home), the organization you're in, an **Open {org} ↗** button, a **CMS** button, and the account menu.
|
|
10
|
+
- **Sidebar**: a **Home** entry, then an **Account** group, then a group for the current organization, then **Platform → Admin** for operators. On mobile the sidebar becomes a slide-out drawer.
|
|
11
|
+
|
|
12
|
+
| Sidebar entry | Path | What's there |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| **Home** | `/home` | The landing page after sign-in: pending invitations, your organizations with **Open** / **CMS** / settings buttons, and a passkey prompt when you have none |
|
|
15
|
+
| Account → **Profile** | `/profile` | Photo, name, email, and **Delete account** |
|
|
16
|
+
| Account → **Security** | `/security` | Password, passkeys, and connected (Google / Cloudflare) logins |
|
|
17
|
+
| Account → **Sessions** | `/devices` | Signed-in devices; sign out one or all |
|
|
18
|
+
| Account → **API keys** | `/api-keys` | Personal API keys (when the `apiKey` plugin is on) |
|
|
19
|
+
| *Org* → **General** | `/$slug` | Name, slug, logo, metadata; **Leave** and **Delete** |
|
|
20
|
+
| *Org* → **Members** | `/$slug/members` | Members and roles, an **Invite** button, and pending invitations |
|
|
21
|
+
| *Org* → **Teams** | `/$slug/teams` | Teams and the active-team picker (when teams are on) |
|
|
22
|
+
| *Org* → **Billing** | `/$slug/billing` | The organization's subscription (when subscriptions are on) |
|
|
23
|
+
| Platform → **Admin** | `/admin` | Users, organizations, subscriptions (operators only) |
|
|
24
|
+
|
|
25
|
+
The shell collapses with your configuration. Without organizations there is no organization switcher and no org group. With nothing to launch (no organizations, no `account.appUrl`, no CMS), Home is skipped and sign-in lands on **Profile**. Old paths redirect, so existing links keep working: `/dashboard` → `/home`, `/passkeys` and `/connected-accounts` → `/security`, `/$slug/settings` → `/$slug`, `/$slug/invitations` → `/$slug/members`.
|
|
8
26
|
|
|
9
|
-
|
|
27
|
+
Served on its own domain (e.g., `auth.example.com`) or at `/account/` when embedded alongside the CMS.
|
|
10
28
|
|
|
11
|
-
|
|
29
|
+
### Getting into the app
|
|
12
30
|
|
|
13
|
-
|
|
31
|
+
There is one rule for every **Open** button: the organization's tenant URL (`account.appUrl` plus `account.tenantPattern` with the slug substituted), else the plain `account.appUrl`, else no button. Opening the app for an organization first makes it the session's active organization, the same way the CMS launch does, so the app never opens into an organization left active by an earlier visit.
|
|
14
32
|
|
|
15
|
-
|
|
33
|
+
Accepting an invitation opens the app for that organization when the project has an app URL. Otherwise it goes to Home.
|
|
16
34
|
|
|
17
|
-
|
|
35
|
+
### Organizations
|
|
36
|
+
|
|
37
|
+
How the organization switcher in the top bar behaves depends on how many organizations you belong to:
|
|
38
|
+
|
|
39
|
+
| Organizations | Top bar | Home |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| 0 | No switcher | Pending invitations and an empty state. **Open** goes to the plain `account.appUrl` when set. |
|
|
42
|
+
| 1 | The org's name as a plain label (no menu) | One large **Open {org}** button, plus **Open CMS** and settings |
|
|
43
|
+
| 2+ | A menu. Picking an org opens it in the app; the gear opens its settings. | One row per org with **Open**, **CMS**, and settings |
|
|
44
|
+
|
|
45
|
+
With exactly one organization, the session starts with it active, so the app, the CMS, and org-scoped API calls default to it. The server does this when the session is created ([Organization Defaults](/platform/auth/plugins/organization-defaults)), and Account UI repeats it for older sessions. Neither overrides an organization that is already active. When `features.pinnedOrganizationId` is set, the shell shows only that organization, so it always behaves as a single-organization account.
|
|
46
|
+
|
|
47
|
+
Some slugs are reserved (`home`, `admin`, `api`, `sudo`, …) because they would shadow a route; the slug field says so as you type. See [Organization Defaults](/platform/auth/plugins/organization-defaults#reserved-organization-slugs).
|
|
48
|
+
|
|
49
|
+
**New organization** appears (on Home and in the switcher) only when the project allows self-serve creation with `plugins.organization.allowUserToCreateOrganization: true`. By default the server closes `POST /organization/create`, and operators create organizations from **Admin → Organizations** instead. See [Admin](/ui/account/features/admin).
|
|
18
50
|
|
|
19
|
-
###
|
|
51
|
+
### CMS launch
|
|
20
52
|
|
|
21
|
-
|
|
53
|
+
When the project also enables the CMS, the top bar and Home have a CMS action. It opens the current organization's CMS directly. Otherwise, one membership opens that organization and several memberships produce a picker. Account UI makes the selected organization active before navigating, so the CMS cannot inherit a different active organization from an earlier session. The action follows `cms.access`: membership is required in `"member"` mode, while only `user.role === "sysadmin"` sees it in `"sysadmin"` mode. A zero-membership sysadmin opens the tenant picker only when `cms.sysadmin: true` explicitly enables cross-tenant scope. When `features.pinnedOrganizationId` is set, the action targets only that fixed organization and never offers the caller's other memberships.
|
|
22
54
|
|
|
23
|
-
### Admin Panel (
|
|
55
|
+
### Admin Panel (operators only)
|
|
24
56
|
|
|
25
|
-
User management
|
|
57
|
+
User management: view all users, search, create accounts, ban/unban, reset passwords, manage sessions, and create organizations with a named owner. It is visible to operator roles (`appmanager`, `sysadmin`) when `auth.admin` is on, and renders inside the same shell. Can be served on its own domain (e.g., `admin.example.com`) via the `adminDomain` config.
|
|
26
58
|
|
|
27
59
|
## How to Enable
|
|
28
60
|
|
|
@@ -54,24 +86,23 @@ npx wrangler deploy
|
|
|
54
86
|
|
|
55
87
|
That's it. The compiler:
|
|
56
88
|
1. Reads your auth feature flags and branding from the config
|
|
57
|
-
2.
|
|
58
|
-
3.
|
|
59
|
-
4.
|
|
60
|
-
5. Bundles the built assets into your Worker alongside the API
|
|
89
|
+
2. Copies the generic prebuilt Account bundle (built once, when the compiler image is built) into `src/apps/account/`
|
|
90
|
+
3. Emits the per-project values (feature flags, URLs, branding) that the Worker injects into every served page as `window.__QUICKBACK_RUNTIME`
|
|
91
|
+
4. Serves the assets from your Worker alongside the API
|
|
61
92
|
|
|
62
|
-
No manual `.env` configuration needed. No separate deployment.
|
|
93
|
+
Compiles never run Vite. No manual `.env` configuration needed. No separate deployment.
|
|
63
94
|
|
|
64
95
|
See [Configuration](/configure) for all `account` options and [Multi-Domain Architecture](/configure/domains) for custom domain setup.
|
|
65
96
|
|
|
66
|
-
### Skip
|
|
97
|
+
### Skip Staging the Account Assets
|
|
67
98
|
|
|
68
|
-
After the first compile, skip
|
|
99
|
+
After the first compile, skip copying the Account assets on subsequent compiles:
|
|
69
100
|
|
|
70
101
|
```typescript
|
|
71
102
|
account: { build: false, /* ...other options */ }
|
|
72
103
|
```
|
|
73
104
|
|
|
74
|
-
|
|
105
|
+
Use it while iterating on API features. Set it back to `true` (or omit it) to pick up a newer Account bundle.
|
|
75
106
|
|
|
76
107
|
### Custom Output Directory
|
|
77
108
|
|
|
@@ -81,28 +112,28 @@ account: { outputDir: "my-custom-path/account" }
|
|
|
81
112
|
|
|
82
113
|
Changes where compiled Account assets are placed, instead of the default `src/apps/account/`.
|
|
83
114
|
|
|
84
|
-
##
|
|
115
|
+
## Feature Gating
|
|
85
116
|
|
|
86
|
-
Auth feature flags control which pages
|
|
117
|
+
Auth feature flags control which pages and controls exist:
|
|
87
118
|
|
|
88
119
|
| Flag | Pages Included |
|
|
89
120
|
|------|---------------|
|
|
90
|
-
| `auth.password` | Password login
|
|
91
|
-
| `auth.emailOTP` | Email OTP login flow, email-based password reset |
|
|
92
|
-
| `auth.passkey` |
|
|
93
|
-
| `auth.organizations` |
|
|
94
|
-
| `auth.admin` | Admin panel (user management) |
|
|
121
|
+
| `auth.password` | Password login; **Change password** on Security |
|
|
122
|
+
| `auth.emailOTP` | Email OTP login flow, email-based password reset; on Security, password changes are confirmed with an emailed code |
|
|
123
|
+
| `auth.passkey` | Passkeys on Security, the `/passkeys/setup` prompt, the passkey nudge on Home |
|
|
124
|
+
| `auth.organizations` | The organization switcher, org cards and invitations on Home, the org sidebar group (General, Members, Teams, Billing) |
|
|
125
|
+
| `auth.admin` | Admin panel (user and organization management) |
|
|
95
126
|
|
|
96
|
-
When a flag is `false`, the corresponding routes **guard themselves at runtime** — each feature route checks its flag from the worker-injected `window.__QUICKBACK_RUNTIME` config in `beforeLoad` and redirects away, and
|
|
127
|
+
When a flag is `false`, the corresponding routes **guard themselves at runtime** — each feature route checks its flag from the worker-injected `window.__QUICKBACK_RUNTIME` config in `beforeLoad` and redirects away, and its sidebar entries and buttons are hidden. The Account SPA ships as one generic prebuilt bundle; flags decide which surfaces exist for your project.
|
|
97
128
|
|
|
98
129
|
## Features
|
|
99
130
|
|
|
100
131
|
- **Authentication** — Email/password, passkeys (WebAuthn), email OTP, email verification, password reset, and the confirm page that magic-link emails open (`/magic-link`)
|
|
101
|
-
- **Account Management** — Profile editing, avatar upload, password changes,
|
|
102
|
-
- **Connected Accounts** — Link Google and Cloudflare logins
|
|
103
|
-
- **Organizations** — Multi-tenant org management with owner/admin/member roles, invitations, and org settings
|
|
132
|
+
- **Account Management** — Profile editing, avatar upload, password changes, session management, account deletion
|
|
133
|
+
- **Connected Accounts** — Link Google and Cloudflare logins on `/security`
|
|
134
|
+
- **Organizations** — Multi-tenant org management with owner/admin/member roles, invitations, teams, billing, and org settings
|
|
104
135
|
- **Admin Panel** — User management dashboard with search, create, ban/unban, password reset, and session viewing
|
|
105
|
-
- **API Keys** — Generate and manage API keys from `/api-keys`
|
|
136
|
+
- **API Keys** — Generate and manage API keys from `/api-keys`
|
|
106
137
|
- **CLI Authorization** — Device authorization flow for `quickback login`
|
|
107
138
|
|
|
108
139
|
## Next Steps
|
|
@@ -68,7 +68,7 @@ auth: {
|
|
|
68
68
|
password: true, // Email/password login + inline password change
|
|
69
69
|
emailOTP: false, // Email OTP login flow
|
|
70
70
|
passkey: true, // WebAuthn passkey setup + management
|
|
71
|
-
organizations: true, //
|
|
71
|
+
organizations: true, // org switcher, Home org list + invitations, org settings
|
|
72
72
|
admin: true, // Admin panel (user management)
|
|
73
73
|
}
|
|
74
74
|
```
|
|
@@ -138,7 +138,7 @@ This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `
|
|
|
138
138
|
|
|
139
139
|
CMS access defaults to `access: "sysadmin"` — only `user.role === "sysadmin"` (the cross-tenant data-plane tier) can use `/cms/*`. Set `access: "member"` to also admit anyone holding an organization membership. `user.role === "appmanager"` opens the CMS in neither mode: it is the control-plane tier and belongs at `/account/admin`. The gate is enforced at multiple layers:
|
|
140
140
|
|
|
141
|
-
- **Account UI** hides
|
|
141
|
+
- **Account UI** hides its **CMS** button for callers outside those roles.
|
|
142
142
|
- **CMS SPA shell** — the Worker redirects unauthenticated requests to login. Sign-in is the only shell-level gate; the app itself is a generic bundle. For a caller `/api/v1/schema` would admit, the Worker also inlines the schema registry in the shell as a non-executing `<script type="application/json" id="__qb-cms-bootstrap">` block, so the CMS starts without fetching it. The block uses the same admission check as `/api/v1/schema`, so it never carries anything that route would refuse. With [Cloudflare Access](/configure/cloudflare-access), it is inlined only when `/api/v1/schema` needs no Access application or the same one the shell request passed. The CMS shell is served `Cache-Control: private, no-store`.
|
|
143
143
|
- **`/api/v1/schema`** returns `401 AUTH_MISSING` to anonymous callers `403 CMS_ACCESS_DENIED` (naming the role required) to signed-in callers outside those roles, and `403 MFA_REQUIRED` to an operator whose session lacks the second factor `auth.operatorMfa` demands, so schema metadata can't be scraped by hitting the API directly.
|
|
144
144
|
- **`custom_view` routes** are gated on `userRole: ["appmanager"]` rather than org membership, so saved views can't be listed or modified without platform-control-plane rights.
|
|
@@ -181,7 +181,7 @@ Start apps ship that setting. A sysadmin who also holds an organization membersh
|
|
|
181
181
|
> **File uploads need valid R2 credentials**
|
|
182
182
|
>
|
|
183
183
|
> Profile pictures and organization logos are **Account UI**, not the CMS — they
|
|
184
|
-
> live at `/account/profile` and `/account/<slug
|
|
184
|
+
> live at `/account/profile` and `/account/<slug>` (the organization's General page). They only work with
|
|
185
185
|
> `account.fileUploads: true`, [managed R2](/platform/storage/r2)
|
|
186
186
|
> (`defineFileStorage("cloudflare-r2", { managed: true })`), and the
|
|
187
187
|
> `R2_ACCOUNT_ID` / `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` secrets. A
|