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 — no shared service data, no shared roles, no shared audit, no shared policies. One platform account can belong to many workspaces (the console surfaces a switcher); membership and permissions are granted per workspace.
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 <platform-access-token>' \
-H 'content-type: application/json' \
-d '{
"slug": "acme",
"display_name": "Acme Inc."
}'Caller becomes owner automatically. Requires a signed-in platform account (cookie or JWT bearer) with a verified email — unverified accounts get 403 EMAIL_NOT_VERIFIED. PAKs (pcft_live_*) cannot create workspaces: 403 PAK_NOT_PERMITTED.
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. One billing relationship per workspace.
- Service data. Auth, Mail, Waitlist, Social data is per-workspace. If your prod and staging data should never touch, separate workspaces guarantee full isolation.
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
A workspace's status is active from creation on; the only lifecycle transition today is deletion.
Deletion: DELETE /v1/workspaces/:slug. Requires the workspace.delete permission (owner-only by default) and a human session — PAKs get 403. No “empty workspace” check — you can delete a workspace with members + data present, so the console asks for confirmation first.
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 identifies the workspace in every workspace-scoped API path.
Slug rules: lowercase alphanumeric + hyphens, 2-64 chars, unique across the platform (409 WORKSPACE_SLUG_TAKEN on conflict). Renaming is supported — PATCH /v1/workspaces/:slug with a new slug — but every URL and API call that referenced the old slug breaks immediately, and the old slug is freed for anyone to claim. Treat renames as an exceptional migration, not routine.
In the console the slug is shown read-only under Workspace → General (only the display name is editable there), so renames go through the API.
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. Handled outside the platform API today.
- Cross-workspace federation. No SSO between workspaces; no shared roles. Two workspaces are independent.