Access Grants

What Are Access Grants?

Access grants are individual permissions given to a user or team on a specific resource. They complement org roles by providing granular control.

Creating a Grant

POST /access-grants
{
  "subject_type": "user",
  "subject_id": "user-uuid",
  "verb": "write",
  "resource_type": "project",
  "resource_id": "project-uuid"
}

The operation is idempotent — creating a duplicate grant returns 200 with the existing grant.

Verbs

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
use	Use the resource

Resource Types

org, project, team, tool_config, notification.

Escalation Prevention

A user can only grant a verb they already hold. You cannot give permissions you don’t have yourself. This prevents privilege escalation through the grant system.

Who Can Grant

• Org admin/owner can grant anything
• Otherwise, the caller must have manage_grants on the target resource AND must already hold the verb they’re granting

Who Can Revoke

• Org admin/owner can revoke any grant
• Otherwise, the caller can revoke grants they created OR if they have manage_grants on the grant’s resource

Listing Grants

GET /access-grants?subject_type=user&resource_type=project

Non-admin callers can only list their own grants — their query params are overridden to force subject_type=user and subject_id=caller.

Related API Endpoints

• POST /access-grants — Create a grant
• GET /access-grants — List grants visible to you
• DELETE /access-grants/{id} — Revoke a grant
• GET /access-events — Query the audit trail