Creating and switching workspaces
Workspace creation and switching both go through the same two backend calls everywhere they appear in the app: POST /workspaces to create, and POST /workspaces/:id/switch to make a workspace active. There is no separate "invite" or "join" flow — these are the only two operations currently exposed.
On this page
Creating a workspace
Every create form in the app collects the same thing: a name, 2–80 characters. The backend also accepts an optional description field (up to 500 characters), but no shipped form currently exposes a description input — every create call the UI makes sends only { name }.
Creating a workspace makes you its OWNER immediately, and the app switches you into it right after creation completes.
New workspace
Name
This exact modal — title "New workspace", single Name field (placeholder e.g. Acme Corp), Cancel / Create — is what both the sidebar dropdown and the Workspaces grid open; the button just reads "Creating…" while the request is in flight.
Name validation is enforced both in the UI and on the server: fewer than 2 characters (after trimming) is rejected. The input has a hard maxLength of 80, so there's no separate max-length warning to see — it simply won't accept more.
Where you can create one
The New workspace action appears in three places, and the first two open the identical modal above:
- The sidebar workspace dropdown → New workspace row at the bottom of the list
- The Workspaces grid → dashed New workspace card
Settings → Workspace tab is different — it's not a modal, but an always-visible inline form:
Create new workspace
All three call POST /workspaces the same way — a plain { name } body — and immediately follow it with POST /workspaces/:id/switch to activate the new workspace.
Switching the active workspace
You can switch your active workspace from:
- The sidebar dropdown — click any workspace in the list
- Settings → Workspace tab — a Switch button on every non-active row
The Control Centre page for a workspace does not have a "switch" button anywhere on it. If you open a campaign from a workspace's Control Centre that isn't your active one, ForgeSend silently switches your active workspace to it first and then takes you to that campaign — an implicit side effect of opening the campaign, not a separate labeled action. See Control Centre for exactly where that happens.
Each explicit switch surface calls POST /workspaces/:id/switch, then reloads: the sidebar re-fetches the current route's data, and Settings does a full page reload after a short delay so every tab reflects the new active workspace.
You can only switch into a workspace you're a member of. Trying to switch into a workspace you don't belong to returns a 403 (ForbiddenException, "You are not a member of this workspace"); switching to an ID that doesn't exist at all returns a 404 (NotFoundException, "Workspace not found"). In the UI this surfaces as an inline error message rather than a silent failure.
What "active" actually means
Your active workspace is stored server-side on your user record (activeWorkspaceId), not in a browser cookie or local state alone — so it's the same active workspace whichever device or session you're on. Every dashboard page (Campaigns, Inboxes, Lists, Analytics, Deliverability, Reply Box) reads and writes against whatever workspace is currently active. Switching workspaces doesn't change your role — your role is per-workspace, tied to your WorkspaceMember record for that specific workspace.
Related docs
Next: Control Centre