What is a workspace?
A workspace is where a small team and its agents do the work. It is the top-level container for everything in Driftless:- Projects and their cards: the work in flight.
- Areas: the navigation domains the system is mapped into.
- Topics and notes: what the team knows, with the Note → Knowledge lifecycle.
- Members, repos, and integrations.
Identity vs. membership
Clerk authenticates the person (the verified session). Belonging to a workspace is a separate fact, stored in Driftless as aworkspace_members row with a role. This decoupling is deliberate: the workspace is the product’s core unit, so it isn’t bound to a billable, capped external resource.
Authorization is a direct membership check: does this verified user have a membership row for the workspace in the URL? A non-member gets a 404 (the workspace reads as if it doesn’t exist), never another tenant’s data.
| Role | Can |
|---|---|
| owner | Everything, including granting the owner role and managing members |
| admin | Merge context into Knowledge, invite members, manage roles (not owner) |
| member | Write notes and propose (merging into Knowledge needs owner/admin) |
How each surface picks the active workspace
| Surface | Authenticates with | Active workspace comes from |
|---|---|---|
| Dashboard | Clerk session (the human) | The URL: app.driftless.icu/w/:slug. The sidebar switcher just changes the slug. |
| CLI | API key | The local registry; driftless workspace switch changes it. |
| MCP | OAuth token | The token’s primary workspace, or an optional workspace argument on a tool call. |
Scoped credentials
A single credential can be authorized for several workspaces, so you authenticate once and reach all of them, without a “super key” that opens everything.- API keys: when you create a key in the dashboard (Settings → API keys), choose its Authorized workspaces.
driftless loginthen registers every workspace the key reaches, andworkspace switchflips between them locally. - OAuth tokens (MCP): the consent screen lets you grant additional workspaces; each tool call can target any of them.
- Membership is the truth. A scoped credential can only reach a workspace while its human is currently a member. Remove someone from a workspace and their credentials there are revoked immediately, no reissue needed.
- No escalation. Inside each workspace, a credential acts with that human’s live role there, never a higher one.