Roles and permissions

This page tells you which role to give a teammate and what that role lets them do, based on the checks the server enforces today.

Prerequisites

You are an owner or admin of the organization (workspace) or of the project you want to manage members in.

The two role sets

An organization (called a workspace in the UI) is the billing and membership boundary; every user gets a personal organization on first use, with the owner role. Organization roles are:

Org role	Meaning
`owner`	The account that created the workspace. The role cannot be changed or transferred through the product.
`admin`	Manages members, invites, workspace settings and GitHub App installations.
`member`	Everyone else.

A project holds requirements. Project roles are owner, admin, qa, developer and viewer; the default for a new project member is developer. Products group projects and reuse the same role set.

How Spectrace resolves your role on a project

When you act on a project, getProjectAccess() computes one effective role from the project's own organization — never from whichever organization you joined first. Precedence:

Your explicit project_members role, if you were added to the project directly.
Otherwise your role on the project's product, if any.
Otherwise your organization role, mapped: org owner → project owner, org admin → project admin, org member → project viewer.

If none of the three exists you have no access. Positive results are cached for 60 seconds; denials are never cached. Changing or removing an org member's role, and adding, re-roling or removing a project member, clear the cache immediately. Accepting an invite does not, so a role granted through an invite can take up to 60 seconds to apply if you already had a cached role on that project.

What each role can do

Only the actions below are role-gated on the server. Some features (cycles, the architecture view and the board layout) also require an explicit project membership row — org-derived access is not enough. Everything else is available to any organization member with access to the project.

Organization actions

Action	Who
Rename the workspace	org `owner`, `admin`
Invite members to the workspace	org `owner`, `admin`
Change a member's role between `admin` and `member`	org `owner`, `admin`
Remove a member (not the owner, not yourself)	org `owner`, `admin`
Install, configure or remove the GitHub App	org `owner`, `admin`

Invited members join as admin or member. Accepting an invite never grants owner, and there is no action to transfer ownership.

Product actions

Action	Who
Create a product	any signed-in user (no role check); the creator becomes the product's `owner`
Attach projects to a product, or move a project between products	effective product `owner`/`admin` on the product, and effective project `owner`/`admin` on every selected project

Project actions

Action	Who
Update project settings	effective `owner`, `admin`
Add, re-role or remove project members	explicit project `owner`, `admin`
Send project invites	explicit project `owner`/`admin`, or org `owner`/`admin`
Change or remove the existing owner, or re-role an existing member to `owner`	nobody
Create requirements	anyone with access except an explicit project `viewer` (an org `member` whose effective role is `viewer` by mapping is not blocked)
Reorder requirements	any effective role except `viewer`
Edit the board layout	explicit project members other than `viewer` (org-derived access is not enough)
Satisfy an approval rule whose approver is a role	explicit project `owner` and `admin` always; otherwise the explicit project member whose role equals the rule's role
Delete a project	any member of the project's organization, when that organization is the caller's first one; no role is checked

Nothing on the server rejects owner on a fresh project invite or on adding a member directly; the web UI does not offer it. For role-based approval rules, org-derived roles do not count, and the requirement's creator cannot approve unless the rule allows self-approval.

Deletion is not role-gated today, and it does not consult your effective project access. Any member of the project's organization — including one whose effective role is viewer — can delete it, provided that organization is the one Spectrace resolves as the caller's first workspace. Deletion is immediate, with no grace period.

`qa` and `developer`

These two roles select who appears in assignment pickers: the QA list shows qa, admin and owner; the developer list shows developer, admin and owner. Beyond that, no server action restricts test-case approval to qa or implementation-status changes to developer. Treat them as labels for assignment, not as permission boundaries.

Integrations

Connecting or disconnecting GitHub, Linear, Jira and Slack is resolved by user and organization, with no role check. The GitHub App installation flow is the exception (owner or admin, above).

AI agents (MCP)

When an AI agent connects with an API key, its permissions come from the key owner's organization role, intersected with any scopes on the key:

Org role	Permissions
`owner`	everything
`admin`	read, write and delete projects, requirements and test cases; read and write members, verifications and approvals
`member`	read projects; read and write requirements, test cases and verifications; read approvals

The role is re-read on every request; a user removed from the organization loses access even if the key still exists. See Connect an agent.

Plans

Role enforcement is identical on every plan. Plan definitions carry a roleBasedAccess flag, but nothing on the server reads it to loosen or tighten the checks above.

Done

A teammate has the intended role when their name appears in the members list with that role and the actions above succeed or fail as the tables say. If an action returns "You don't have permission…", the caller's effective role is below the threshold — check the explicit project role first, then the organization role.