Workspace

Team Management

Throttle organises access around workspaces and applications. A workspace is the billing and membership boundary; each workspace can contain multiple applications and multiple workspace environments. Role assignments exist at the workspace and application levels, while environment grants decide which production or non-production environments a member can see.

Workspaces vs applications

A workspace is the top-level container. It holds subscription and billing state, and every member with a workspace-level role can act across all applications inside it. An application maps to one storefront or integration surface. Aworkspace environment is the isolation layer shared across applications: production is immutable, and custom environments such as test, UAT, QA, and staging are non-production sandbox-provider environments.

Workspace concepts

One owner — the Clerk user who created the workspace.
Unlimited workspace admins — implicit admin on all applications.
Members with per-application roles.
Shared billing across all applications.
Environment grants for production, all non-production, or selected environments.

Application concepts

Scoped API keys, webhooks, and checkout sessions.
Per-member roles: admin, developer, finance, viewer.
Reads and writes are filtered by the active workspace environment.

Roles

Throttle checks two role axes for every request: the caller's workspace role and, for application-scoped actions, the caller's application role on the specific application being accessed. A permission is granted if either axis satisfies the rule — see the Permissions reference for the full matrix.

Workspace roles

owner — assigned to the workspace creator; one per workspace; cannot be transferred via the API (use the transfer ownership flow). Holds every permission, including workspace deletion and billing management.
workspace_admin — full administrative access across all applications. Can invite members, edit member roles, and manage application settings. Cannot delete the workspace or access billing.

Application roles

admin — manage application settings, API keys, webhooks, and all member roles within the application. Can invite new members to the workspace with an application-scoped role.
developer — access API keys, webhooks, customers, and orders (read and write). Cannot change application settings or member roles.
finance — read customers, orders, payments; issue refunds. No write access to orders or customers.
viewer — read-only access to customers, orders, and payments.

Who can invite

Invite rights depend on the inviter's own role. You can never grant a role higher than your own.

Inviter role	Can invite as	Application scope
`owner`	Any role (including workspace_admin)	Any application in the workspace
`workspace_admin`	Member with any application role	Any application in the workspace
`admin` (application member)	Member with `developer`, `finance`, or `viewer`	Only the applications they are admin on

workspace_admin cannot invite workspace_admin

Only the owner can grant the workspace_admin role. This maps to the workspace:invite-admin permission.

Environment grants

Environment grants are workspace-wide. They sit beside roles: a member must have the right role for the action and access to the active environment. Owners and workspace admins can set grants on invites and member edits; application admins can invite members only into their current application and those invites default to all non-production environments.

grantType	Meaning
`all`	All active environments, including production and future custom environments.
`all_non_production`	Every active non-production sandbox-provider environment.
`production_only`	Only the immutable production environment.
`selected`	Only the listed environment UUIDs.

Denied environment selection

A dashboard or Clerk-authenticated API request for an environment outside the member's grant returns 403 member_env_forbidden.

Invite lifecycle

Invitations are short-lived signed tokens. The flow from creation to membership is:

Create — POST to /api/v1/workspaces/{workspaceId}/invites with the invitee email and target role(s). Throttle mints a 7-day JWT and emails the invite link.
Email sent — the invitee receives a link to /accept-invite?token=... from Throttle. The email address on the invite must match the Clerk account used to accept.
Resend — POST to /api/v1/workspaces/{workspaceId}/invites/{id}/resend. Throttle rotates the token (old token is immediately invalidated) and sends a fresh email with a new 7-day window.
Revoke — POST to /api/v1/workspaces/{workspaceId}/invites/{id}/revoke. The token is killed immediately and the invitation can no longer be accepted.
Accept — see the accept flow section below.

Token properties

Signed JWT — tamper-proof and server-verified on accept.
7-day TTL from creation or last resend.
Single-use — accepting invalidates the token.
Strict email match — the signing email must equal the Clerk account email.

Invite states

pending — awaiting acceptance, token valid.
accepted — member joined, token consumed.
revoked — cancelled by an admin; token dead.
expired — TTL elapsed before acceptance.

Accept flow

Accepting an invitation binds a Clerk user to the workspace membership record.

The invitee clicks the link in the email and lands on /accept-invite?token=....
If not already signed in, the invitee authenticates via Clerk. The Clerk email must exactly match the address the invite was sent to — mismatches are rejected with invite_email_mismatch.
The browser POSTs the token to POST /api/v1/invites/accept with the Clerk session JWT in the Authorization header.
On success the member record is created, role assignments are applied, and the invitee is redirected to the workspace dashboard.

Already a member?

If the accepting user is already a member of the workspace, the API returns 409 already_member. Existing roles are not modified.

Member management

After a member joins, their roles and access can be adjusted at any time by users with sufficient permissions.

Workspace-level actions

List members — GET /api/v1/workspaces/{workspaceId}/members. Returns workspace role, per-application role assignments, and environment grants.
View own membership — GET /api/v1/workspaces/{workspaceId}/members/me. Returns the calling user's roles without requiring elevated permissions.
Change workspace role — PATCH /api/v1/workspaces/{workspaceId}/members/{memberId}. Supply the new workspaceRole. Requires workspace:edit-member. Owners and workspace admins may also supply environmentGrants.
Remove from workspace — DELETE /api/v1/workspaces/{workspaceId}/members/{memberId}. Revokes all application roles and the workspace membership in one call.

Application-level actions

Grant or change app role — include applicationRoles in the PATCH body. Each entry is { applicationId, role }.
Revoke single app access — DELETE /api/v1/workspaces/{workspaceId}/members/{memberId}/applications/{applicationId}. Removes only the specified application role; workspace membership is kept.