Roles & Permissions

Forgecroft uses org roles as a baseline and composable access grants for fine-grained control.

Org Roles

Every org member has one role:

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

Ownership rules

• Only owners can promote users to admin or owner.
• Only owners can change another owner’s role.
• You cannot change your own role.
• Owners cannot be demoted by non-owners.

Fine-Grained Verbs

Verbs grant granular permissions on specific resources, independent of org role:

Verb	Allows
read	View the resource
write	Modify the resource
delete	Remove the resource
manage_members	Add/remove members
manage_grants	Create/revoke access grants
use	Use the resource (e.g., a tool config)

Access Grants

Access grants assign verbs to subjects on specific resources:

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

Subject types: user (a specific user) or team (all members of a team).

Resource types: org, project, team, tool_config, notification.

Escalation prevention: You can only grant a verb you already hold. You cannot give permissions you lack.

Access Resolution

When determining effective access to a resource, Forgecroft checks in this order:

Priority	Condition	Effective Access
1	Org owner or admin	admin
2	write grant on the parent project	admin
3	write grant on the resource	admin
4	read grant on the project or resource	member
5	Org reader role	member (reads only)
6	No matching grant	forbidden

Verb sets by effective access level

Level	Verbs
admin	read, write, delete, manage_members, manage_grants, use
member	read

Audit Trail

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

API Endpoints

Endpoint	Description
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 /projects/{id}/members	Add a project member
POST /teams/{id}/members	Add a team member