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": "workspace",
  "resource_id": "workspace-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
`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

Resource Types

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. 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=workspace

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

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