Member roles

Every membership carries one of three roles. Roles are how the console summarises capability tiers; under the hood each role is a bundle of permission scopes that gate individual API routes. The console hides anything the caller can’t reach.

Role	Manages config	Runs work	Manages people	Sees audit
Owner	Yes	Anywhere in the org	Yes	Org-wide
Operator	Yes	Anywhere in the org	No	Org-wide
Member	No	Only their workspaces	No	Only events they caused

Specifically:

• Owner is the only role that can invite / remove members and promote / demote others. Owners also hold every Operator-tier capability and can manage billing. Two-Owner organisations are the norm (so the org survives a single Owner leaving) — the API enforces a last-Owner guard on demote / remove.
• Operator handles every config resource (providers, agent roles, content packs, credentials, secrets) and can act on every workspace in the org. Operators can issue API keys but can’t invite people or change anyone’s role.
• Member can submit tasks against their own workspaces and read their own data. They see every other member in the org by name (so they can @-mention or know who to ask), but can’t change anyone’s role or invite new people.

API keys are issued under one of three permission templates that map to a strict subset of these capability tiers — see API keys for the templates and the rationale for what’s excluded.

Default scope sets

These are the scopes WorkOS attaches to each role at sign-in. The permissions reference explains what each one gates.

Role	Scopes
Owner	caps:write, auth:write, secrets:write, workspace:read, workspace:write, tasks:write:own, audit:read, members:read, members:write, apikeys:write, billing:write
Operator	Same as Owner minus members:write, billing:write
Member	workspace:read:own, workspace:write:own, tasks:write:own, audit:read:own, members:read, auth:write:own

A couple of things worth calling out:

• Nobody holds the unscoped tasks:write — even Owners get only tasks:write:own. Operating an agent in someone else’s session would muddy attribution and audit; the supported pattern for “I need to investigate that workspace” is fork the workspace and act in your own copy.
• Some routes additionally enforce Identity.Role == Owner inline on top of the scope check. Member-management mutations (invite as Owner, change someone’s role, remove someone) are the only places this fires today; it’s hierarchy logic, not a separate scope.

Changing a member’s role

Promote / demote happens through the console (Settings → Members) or the API (PATCH /v1/orgs/{id}/memberships/{user_id}). The caller must be an Owner.

Pending invitations carry their role on the invitation record, not on a separate membership. Updating the role of a pending invite isn’t supported (WorkOS limitation) — revoke and re-invite.