Userbox model

Userbox manages identity and access for multi-tenant applications. Everything in Userbox is organized around a five-level hierarchy. Understanding this hierarchy is the prerequisite to understanding every other concept in the docs.

The hierarchy

Account
  └── Environments  (development · staging · production)
        └── Workspaces  (access contexts for your users)
              └── Memberships  (user ↔ workspace connections)
                    └── Permissions  (platform or app-defined)

Each level scopes the one below it. A permission check always asks: "Does this user have permission X inside workspace Y?" — never globally.

Account

Your account is the top-level entity in Userbox. It maps to your product or organization. All environments, users, API keys, and configuration belong to a single account.

Most teams have one account. You might have separate accounts for clearly distinct products, but not for development vs. production — that is what environments are for.

→ Continue to Environments

Environments

Every account ships with three environments: development, staging, and production. Environments are fully isolated — data, API keys, and configuration in development never mix with production.

API keys are environment-scoped. A key created in development will not work in production. This is intentional.

→ Continue to Environments

Workspaces

A workspace is an access context inside an environment. Workspaces let you model the organizational boundaries of your application — for example, one workspace per customer organization in a B2B SaaS.

Every permission check in Userbox is workspace-scoped: the same user can have different permissions in different workspaces.

→ Continue to Workspaces

Memberships

A membership connects a user to a workspace. A user can be a member of multiple workspaces. Memberships can carry roles, belong to groups, and receive explicit permission grants.

There is no such thing as a "global" permission that applies across all workspaces. Permissions are always scoped to a membership.

Permissions

Userbox has two kinds of permissions:

• Platform permissions control access to Userbox itself — the console, user management, API key management. → Platform permissions
• App permissions are custom permissions you define for your own application — finance.payables.approve, health.reports.view. → App permissions

What's next

• Environments — Understand isolation and API key scoping
• Workspaces — Choose the right workspace pattern for your app
• Platform permissions — Configure console access for your team
• App permissions — Define and check permissions in your application