Workspace Switching

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 tenants 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 tenant 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.

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.

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 tenant 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 tenant 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-tenant 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.