Workspace

Permissions Reference

Every dashboard action maps to a named permission. A permission is granted when the caller's workspace role or their application role on the target application satisfies the rule — whichever axis applies first wins. See Team management for how roles are assigned.

Permissions gate humans; scopes gate API keys

This page describes role-based permissions (RBAC) — the rules that gate human users authenticating with a Clerk session in the dashboard. They are a separate system from API key scopes, which gate machine-to-machine calls made with an sk_ / pk_ key. A Clerk caller carries the wildcard scope and is gated purely by these permissions; an API-key caller is gated purely by its scopes and never by RBAC. The two systems compose; neither replaces the other.

How permission checks work

For each request Throttle resolves two values from the auth context: the caller's workspace-level role (owner | workspace_admin | none) and their application-level role on the specific application being acted on (admin | developer | finance | viewer | none). A permission is granted if either role set contains the caller.

Workspace roles are implicitly elevated

owner and workspace_admin satisfy most application-level permissions without needing an explicit per-application role. They act as supersets of any application role on any application in the workspace.

Environment grants are a separate gate

Roles answer “can this person perform the action?” Environment grants answer “can this person use the selected workspace environment?” A caller must pass both checks. Requests outside the member's environment grant return 403 member_env_forbidden.

The permission check is exposed at GET /api/v1/auth/permissions. The response lists every permission key and whether it resolves to true for the authenticated caller, optionally scoped to a specific application via the x-application-id header.

Permission catalog

The table below lists every permission string, which workspace roles satisfy it, and which application roles satisfy it. A dash (—) means that role axis is not checked for that permission.

Permission	Workspace roles	Application roles
`workspace:delete`	owner	—
`workspace:transfer`	owner	—
`workspace:billing`	owner	—
`workspace:invite-admin`	owner	—
`workspace:settings`	owner, workspace_admin	—
`workspace:invite`	owner, workspace_admin	admin
`workspace:edit-member`	owner, workspace_admin	—
`workspace:remove-member`	owner, workspace_admin	—
`workspace:read-team`	owner, workspace_admin, member	—
`application:settings`	owner, workspace_admin	admin
`application:api-keys`	owner, workspace_admin	admin, developer
`application:webhooks`	owner, workspace_admin	admin, developer
`application:customers:write`	owner, workspace_admin	admin, developer
`application:customers:read`	owner, workspace_admin	admin, developer, finance, viewer
`application:orders:write`	owner, workspace_admin	admin, developer
`application:orders:read`	owner, workspace_admin	admin, developer, finance, viewer
`application:refunds:issue`	owner, workspace_admin	admin, developer, finance
`application:payments:read`	owner, workspace_admin	admin, developer, finance, viewer
`application:edit-app-member`	owner, workspace_admin	admin
`application:extensions:read`	owner, workspace_admin	admin, developer, finance, viewer
`application:extensions:write`	owner, workspace_admin	admin, developer
`application:extensions:install`	owner, workspace_admin	admin, developer
`application:extensions:admin`	owner, workspace_admin	admin

Permission scope notes

Workspace-only permissions

workspace:delete, workspace:transfer, workspace:billing, and workspace:invite-admin are exclusively for the owner. No application role satisfies these.
workspace:settings covers workspace branding, sender domains, and workspace-scoped email settings.
workspace:edit-member and workspace:remove-member require workspace_admin or above; no application role grants them.

Read vs write split

The finance role sees customers, orders, and payments but cannot write to customers or orders. It can issue refunds.
The viewer role is fully read-only. It cannot issue refunds or perform any write action.
The developer role is the same as finance plus write access to customers and orders, and access to API keys and webhooks.

Check permissions at runtime

Call GET /api/v1/auth/permissions with a Clerk JWT. Pass x-application-id to resolve application-level role flags for a specific application. The response shape is:

{
  "workspaceRole": "workspace_admin",
  "appRole": "developer",
  "permissions": {
    "workspace:delete": false,
    "workspace:invite": true,
    "application:api-keys": true,
    "application:customers:write": true,
    ...
  }
}

Build UI conditionals from this endpoint

The dashboard uses this response to show or hide actions in the UI. Call it once on page load and cache client-side for the session duration.