The workspace is the boundary.
One workspace = one team's data, one team's settings, one team's billing. Everything ProductCraft owns is keyed by workspace_id. Get the boundary right and the rest follows.
1
What a workspace owns
Inside one workspace:
- Members with roles (Chapter 2).
- Service activations — Auth apps, Mail domains + templates, Waitlist waitlists, Social communities (Chapter 3).
- PATs for CI/CD access (Chapter 4).
- Audit log recording every member + role + service mutation (Chapter 5).
Two workspaces are fully isolated. They share no members (you can be in both as separate accounts; the platform UI surfaces a switcher), no service data, no audit, no policies. Crossing the boundary requires explicit re-auth.
2
Create a workspace
From the console, sign up + name the workspace. Or via API (rare, but useful for automated team-provisioning):
curl https://api.platform-auth.productcraft.co/v1/workspaces \
-H 'authorization: Bearer <your-platform-cookie-or-bearer>' \
-H 'content-type: application/json' \
-d '{
"slug": "acme",
"display_name": "Acme Inc.",
"description": "Acme team workspace."
}'Caller becomes owner automatically. Requires email-verified on the platform account — unverified accounts get 412.
3
One workspace or many?
A real question new customers ask: separate workspace per environment (prod / staging / dev), or one workspace with multiple apps?
The right answer depends on:
- Member overlap. Same people work on all environments → one workspace, less churn. Different teams own prod vs dev → separate workspaces, blast-radius control.
- Audit boundary. Need totally separate audit feeds for compliance → separate workspaces. Cross-cutting visibility is fine → one workspace.
- Billing. Today one workspace = one billing relationship. Multi-org billing is on the roadmap; for now, one billing entity per workspace.
- Service data. Auth, Mail, Waitlist, Social data is per-workspace. If your prod and staging data should never touch, separate workspaces give you the cryptographic isolation for free.
Recommended for most teams: one workspace per company, multiple apps inside it (e.g. acme, acme-staging). The cryptographic + database isolation between Auth apps already prevents staging from touching prod data; member overlap usually outweighs the audit-separation benefit.
4
Workspace lifecycle
Status states:
active— everything works.suspended— operator-disabled. Rare. Surfaced as “workspace suspended” in the UI.
Deletion: DELETE /v1/workspaces/:slug. Owner-only. No “empty workspace” check — you can delete a workspace with members + data present. The UI surfaces a confirmation showing the member count + active services so it's an informed click.
Deletion is irreversible. Auth apps, Mail domains, Waitlist waitlists, every audit row — gone. Take an export of anything you care about first.
5
The workspace slug
The slug appears in console URLs and as part of some service paths. Pick well — slug changes today are not supported.
Slug rules: lowercase, alphanumeric + dashes, 3-32 chars, unique across the platform. Reserve a slug at signup that matches your company name; renaming later requires customer support intervention (under the hood it's possible, but the surface assumes immutability).
6
What's not in workspaces
- End-user identity. Your customers' users (the people signing up for the product you ship) live in Auth, not in the workspace. The workspace owns the Auth app they sign up to.
- Billing details. Coming in a separate billing service; today managed by hand.
- Cross-workspace federation. No SSO between workspaces; no shared roles. Two workspaces are independent.