Skip to main content

Scopes & Workspaces

Authentication tells Lexabit who you are. A scope tells it which context you're working in for a given request. Almost every request runs under a scope, and the same request under a different scope can return completely different data.

Scope = workspace

From a user's perspective, a scope is a workspace — the space you're currently working in. Switching workspace in the Portal is the same thing as changing scope in the API. This page uses "scope" for the API mechanism and "workspace" for the idea it represents.

A scope is one of your entities​

A scope isn't a separate thing bolted onto the entity model — it is an entity you're operating within. Your available scopes are entities such as:

  • the tenant — your organisation's account, the broadest scope (see The Tenant);
  • a team or group — a narrower collaboration space;
  • and other entities you've been granted access to operate within.

The tenant is usually the scope you work under by default — it's the widest, and it contains everything else — but it's important to see it as one scope, not a special container your account is locked into. You operate under whichever scope you choose; the tenant just happens to be the biggest and most common one.

Discover the scopes (workspaces) you can act in:

curl "https://api.lexabit.com/scopes/v1" \
  -H "Authorization: Bearer $LEXABIT_TOKEN"

Selecting a scope: the X-Scope header​

Each scope in GET /scopes/v1 comes with a scopeId — that's the value you put in the X-Scope header:

// GET /scopes/v1
{
  "data": [
    { "scopeId": 42, "id": "2f5a9c1e-…", "type": "tenant", "name": "Acme Law" },
    { "scopeId": 91, "id": "7b3f0a91-…", "type": "team",   "name": "Corporate" }
  ]
}

Send the scopeId of the scope you want to operate in with each scoped request:

X-Scope: 42
Treat scopeId as opaque, and note it is not the entity id

scopeId is the scope's own identifier — not the entity's id. Send it back exactly as GET /scopes/v1 returned it; don't construct it or assume its format (it's an integer today, but treat it as an opaque token — it may change form later). The entity's id (a UUID) is a different value and is not accepted in X-Scope.

If a scoped endpoint is called without X-Scope, it fails with 400 (error.code = "bad_request", "scope not set") rather than guessing or returning everything. See API Conventions.

How scope changes what you see​

Scope narrows visibility. List endpoints return only the records reachable from the active scope, so the same token calling the same endpoint returns different results depending on the scope:

  • Under your tenant's scope you might see every client in the organisation.
  • Under a team's scope you see only what that team can reach.

A user working across several teams or clients switches scope (workspace) to move between those views — they don't see everything at once.

Scope in the access model​

Scope drives the Visibility layer of Lexabit's four-layer access model:

  1. Authentication — who you are (your token).
  2. Visibility — which entities are in view, set by your active scope.
  3. Entitlement — whether your role grants the capability.
  4. Action — whether you can do it to this specific entity.

Being in a scope doesn't grant access to everything in it; permissions still apply within it. See Permissions for how that resolves — including why an entity outside your active scope returns 404 rather than 403.

See also​