Roles & Permissions

Understand the role hierarchy, fine-grained verbs, and composable access grants that control who can do what.

Forgecroft uses a layered permission model: org roles provide a baseline, and fine-grained access grants add composable permissions on top.

Org Roles

Every org member has one of four roles:

Role	Capabilities
`owner`	Full control. Cannot be demoted by others. Can manage billing, delete the org.
`admin`	Manage members (except owners), create API keys, update org settings, manage all resources.
`member`	Default role. Can work within projects and workspaces they have access to.
`reader`	Read-only access to org resources.

Role Hierarchy

owner (2)
  └── admin (1)
        └── member (0)
              └── reader (-1)

Only owners can promote users to admin. Only owners can change the owner’s role. You cannot change your own role.

Fine-Grained Verbs

Beyond org roles, Forgecroft uses verbs for granular permissions on specific resources:

Verb	What it allows
`read`	View the resource
`write`	Modify the resource
`delete`	Remove the resource
`manage_members`	Add/remove members
`manage_grants`	Create/revoke access grants
`trigger`	Start a run
`apply`	Execute an apply run
`approve`	Approve a pending run
`reject`	Reject a pending run
`abort`	Cancel an in-progress run
`force_unlock`	Release a stale state lock
`use`	Use the resource (e.g., credentials)

Access Grants

Access grants are composable permissions that can be given to users or teams on specific resources:

{
  "subject_type": "user",
  "subject_id": "user-uuid",
  "verb": "write",
  "resource_type": "workspace",
  "resource_id": "workspace-uuid"
}

Subject Types

user — A specific user
team — All members of a team

Resource Types

Access grants can target: org, project, workspace, run, credential, vcs, state_backend, tool_config, policy_set, team, approval_rule, notification.

Escalation Prevention

A user can only grant a verb they already hold. You cannot give permissions you don’t have yourself.

Workspace Access Hierarchy

When determining a user’s effective access to a workspace, Forgecroft checks in order:

Org owner/admin → always admin access
Project admin (via access grant with write on the parent project) → admin
Direct workspace admin (via access grant with write on the workspace) → admin
Project member or workspace member (via read grant) → member
Org reader → member baseline for reads
No matching grant → forbidden

Workspace Member Verbs

When added as a workspace member, users receive a set of verbs:

Role	Verbs
`admin`	`read`, `write`, `delete`, `manage_members`, `manage_grants`, `trigger`, `apply`, `approve`, `reject`, `abort`, `force_unlock`
`member`	`read`, `trigger`, `approve`

Approvers get only the approve verb — they can approve runs but cannot modify the workspace.

Audit Trail

All access grant operations are recorded in the access event audit trail. Query with GET /access-events filtered by subject, resource, or time range. Only org admins can view audit events.

GET /org/members — List org members
PATCH /org/members/{userId} — Change a member’s role
DELETE /org/members/{userId} — Remove a member
POST /access-grants — Create an access grant
GET /access-grants — List grants visible to you
DELETE /access-grants/{id} — Revoke a grant
GET /access-events — Query the audit trail
POST /workspaces/{id}/members — Add a workspace member
POST /workspaces/{id}/approvers — Add an approver