Workspaces: Create, Invite & Switch

What a workspace is#

A workspace is the unit you actually work inside — its own products, rate plans, customers, invoices, and usage data. Everything in Aforo is isolated by workspace: data in one workspace is never visible from another.

An organization is the parent that can own several workspaces. SmartAI is one organization; its IT and Product Eng workspaces are two separate, fully-isolated environments under it. You sign in once and reach every workspace you have a seat in — across organizations, not just one.

How your access is decided#

When the console asks “which workspaces can this person reach, and with what role?”, it does not read a baked-in list from your sign-in token. It resolves the answer live from the database, keyed on your identity, every time the picker loads. Two things grant a seat:

• A direct workspace membership. You are a member of that specific workspace with a role — Owner, Admin, Billing admin, and so on.
• An organization membership you inherit down. If you are an org owner or org admin, you inherit access to every workspace that organization owns. An org owner lands as Owner in each; an org admin lands as Admin.

Because the list is resolved live and keyed on you, two things follow that matter in day-to-day use: a seat granted a minute ago appears on your next picker load, and a seat revoked a minute ago disappears just as fast. Nothing is “stuck” in an old token.

Switching between workspaces#

You can switch as often as you like, in either direction. There are two routes to the same place, and which one you reach for depends on where you are when the urge strikes.

From inside a workspace — the header menu#

Open your profile menu in the top-right of any workspace and choose Switch Workspace. That takes you to your account home, where every workspace you belong to is listed; pick one and you land inside it.

From a fresh sign-in — the workspace picker#

When you sign in and you are not already pointed at a specific workspace, Aforo shows the picker (below). It is the same destination the header menu sends you to. Each switch issues a fresh, single-use handoff so the move is clean — there is no shared link to leak and no stale code to reuse.

The workspace picker#

The picker groups your workspaces under the organization that owns them. Here is exactly what a SmartAI admin sees — two workspaces under SmartAI plus a Finance workspace under GlobalAI they also have a seat in:

Reading a row, left to right:

• Organization header (SmartAI, GlobalAI) — the parent. The chip beside it (Org admin) is your role over the organization, if any. SmartAI shows it; GlobalAI does not, because here you only hold a single-workspace seat.
• Workspace name + slug (IT · smartai-it) — the workspace you enter when you click Open.
• Your role in that workspace (Owner, Admin, Billing admin) — what you can do once inside. The same person can be Owner in one workspace and Billing admin in another.

Creating a workspace#

Need a clean, separate space — a second environment, a new business unit, or a dedicated workspace for a specific customer? An org owner or org admin provisions a new workspace from the organization console. It comes up fully isolated under your organization — its own products, rate plans, customers, and invoices, sharing nothing with your other workspaces.

1. Open the Organization console at /organization and select the Workspaces tab. You need to be an org owner or org admin; other roles see the list read-only.
2. Choose New workspace, give it a name, and create it.
3. Aforo provisions the workspace and seeds its default billable units, so it’s ready for its own catalog and pricing right away.

Closing a workspace or organization#

Aforo exposes three “Danger Zone” consoles, and they read as duplicates until you know each one’s scope. They aren’t — each acts at a different level of the tenant hierarchy, and each is reachable from a different place in the sidebar. The right one depends on what you’re trying to end.

Two more things worth knowing before you act:

• Deactivate is not the same as Delete. On a workspace, Deactivate is a soft-stop — members lose access, the workspace comes back with the in-page Reactivate button, and the data is preserved during the grace window. Delete schedules permanent removal across every Aforo service — a restore link is emailed to all workspace owners as the only recovery path.
• Aforo blocks a workspace close on active billing. If the workspace has any active subscriptions or unsettled invoices, the pre-flight guard on Deactivate and Delete surfaces the blockers before you type the confirmation phrase. Resolve those first; Aforo re-runs the same guard server-side.
• Single-workspace organizations. If your organization contains exactly one workspace, archiving the org effectively ends that workspace too. In that case, closing the workspace directly (with the 30-day grace + email restore path) is usually what you actually want — the Organization status page calls this out inline when it detects the single-workspace shape.

Giving someone access#

Say a SmartAI admin (call them A) wants a colleague (B) to work in a SmartAI workspace. B will see and switch into that workspace once their invite is bound to their identity — not just their email address. There are two ways to invite, and they bind at different moments.

Invite to the whole organization#

Best when a teammate should reach every workspace your organization owns.

1. Open the Organization console (/organization) → Members tab. You need to be an org owner or org admin.
2. Choose Add member, enter their email, and pick an organization role.
3. Send. They show as Invited; on their first sign-in the seat binds to their account and they inherit access to every workspace the organization owns.

Invite to a single workspace#

Best when access should stay scoped to one workspace — a contractor on one project, a teammate who only needs one environment.

1. Switch into the target workspace, open the Workspace Admin, and select the Members tab. You need to be the workspace Owner.
2. Invite by email and assign a workspace role — Admin, Billing admin, Developer, or Viewer.
3. Send. The seat binds when they join through the membership flow; until then it’s pending and the workspace won’t appear in their picker.

Roles reference#

Roles are assigned when you invite, and a person can hold a different role in each workspace. Workspace roles govern what you can do inside a workspace; organization roles govern the parent and inherit down.

Do I need to log in again to see a new workspace?#

No. The picker list is read live from the database against your identity, not from your sign-in token. The moment a new seat is granted — you provision a workspace, an admin adds you, an org invite binds — it shows up on your next picker load. No sign-out, no token refresh, no service restart.

The only nuance: the picker caches its result for about 30 seconds to stay snappy, so a brand-new seat appears on the next refresh rather than the same instant. That is a refresh, not a re-login. And switching into a workspace never re-authenticates you — the handoff carries your existing session; only the workspace context changes.

What carries over, and what resets#

A switch changes which workspace you are operating in — so the console deliberately clears anything tied to the workspace you just left, while keeping anything tied to you.

Enumerate your workspaces in code#

Switching is a console action — you click, you do not script it. But if you are automating an internal tool and want the list of workspaces your session can reach, the console reads it from one endpoint. Call it with your operator session token:

curl https://org.aforo.ai/me/organizations \
  -H "Authorization: Bearer $AFORO_SESSION_TOKEN"

The response mirrors the picker exactly — organizations, each with its workspaces and your role:

{
  "organizations": [
    {
      "org": { "organizationId": "org_smartai", "slug": "smartai", "name": "SmartAI", "status": "ACTIVE" },
      "orgRole": "ORG_ADMIN",
      "workspaces": [
        { "tenantId": "tenant_smartai_it",      "slug": "smartai-it",      "name": "IT",          "role": "OWNER" },
        { "tenantId": "tenant_smartai_prodeng", "slug": "smartai-prodeng", "name": "Product Eng", "role": "ADMIN" }
      ]
    },
    {
      "org": { "organizationId": "org_globalai", "slug": "globalai", "name": "GlobalAI", "status": "ACTIVE" },
      "orgRole": null,
      "workspaces": [
        { "tenantId": "tenant_globalai_finance", "slug": "globalai-finance", "name": "Finance", "role": "BILLING_ADMIN" }
      ]
    }
  ]
}

What workspace switching does not do#

Switching changes where you stand; it never merges or shares data. Worth being explicit, because the single sign-in can make it feel like the workspaces are connected under the hood — they are not.

• It does not pool data across workspaces. Products, customers, invoices, and usage stay isolated per workspace. A switch points you at one workspace at a time; there is no combined view.
• It does not copy your role across. Being Owner in IT does not make you Owner in Product Eng. Each seat carries its own role.
• It is not a way to grant access. You can only switch into a workspace you already have a seat in. To add a teammate, use an invite (see Giving someone access).
• A teammate working in your workspace is operating under that workspace’s isolation boundary — intended shared access for a shared workspace, not a cross-workspace leak.

Troubleshooting#

Managing who belongs where is the other half of this story — see SCIM Provisioning to drive membership from your identity provider, so seats appear and disappear in lockstep with your directory.