> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedrock.quarry-systems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Governance

> Managing user access across your organization with Bedrock

## Overview

User governance in Bedrock follows a hierarchical Role-Based Access Control (RBAC) model. Users are added to scopes via memberships, assigned roles, and inherit permissions from those roles. This guide covers common patterns for managing user access.

## Core Concepts

<CardGroup cols={2}>
  <Card title="Subjects" icon="user">
    Users are registered as subjects with `subjectType: "user"`
  </Card>

  <Card title="Memberships" icon="id-card">
    Memberships connect users to scopes
  </Card>

  <Card title="Roles" icon="user-shield">
    Roles group permissions together
  </Card>

  <Card title="Permissions" icon="key">
    Permissions define specific actions
  </Card>
</CardGroup>

## Example: Enterprise Organization

Let's set up a typical enterprise structure with organizations, departments, and teams.

### 1. Define the Hierarchy

```bash theme={null}
# Create all scope types at once
curl -X POST 'https://api.example.com/scope-types/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "type_org", "name": "Organization", "config": {"permissionMode": "override"}},
    {"id": "type_dept", "name": "Department", "config": {"permissionMode": "inherit"}},
    {"id": "type_team", "name": "Team", "config": {"permissionMode": "inherit"}}
  ]'

# Define hierarchy: Org → Department → Team
curl -X POST 'https://api.example.com/scope-type-hierarchy' \
  -d '{"parentTypeId": "type_org", "childTypeId": "type_dept"}'

curl -X POST 'https://api.example.com/scope-type-hierarchy' \
  -d '{"parentTypeId": "type_dept", "childTypeId": "type_team"}'
```

### 2. Create Scopes

```bash theme={null}
# Create all scopes at once
curl -X POST 'https://api.example.com/scopes/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "scope_acme", "name": "Acme Corp", "typeId": "type_org"},
    {"id": "scope_engineering", "name": "Engineering", "typeId": "type_dept"},
    {"id": "scope_marketing", "name": "Marketing", "typeId": "type_dept"},
    {"id": "scope_platform", "name": "Platform Team", "typeId": "type_team"},
    {"id": "scope_frontend", "name": "Frontend Team", "typeId": "type_team"}
  ]'

# Link hierarchy
curl -X POST 'https://api.example.com/scope-hierarchy/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"parentScopeId": "scope_acme", "childScopeId": "scope_engineering"},
    {"parentScopeId": "scope_acme", "childScopeId": "scope_marketing"},
    {"parentScopeId": "scope_engineering", "childScopeId": "scope_platform"},
    {"parentScopeId": "scope_engineering", "childScopeId": "scope_frontend"}
  ]'
```

### 3. Define Roles at Different Levels

Roles can be defined at any scope level and then assigned to memberships at that scope or any child scope (assignment is explicit—defining a role higher up does not grant it automatically lower down):

```bash theme={null}
# Create all roles at once
curl -X POST 'https://api.example.com/roles/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "role_org_admin", "name": "Org Admin", "description": "Full organization access", "scopeId": "scope_acme"},
    {"id": "role_org_member", "name": "Org Member", "description": "Basic organization access", "scopeId": "scope_acme"},
    {"id": "role_dept_manager", "name": "Dept Manager", "description": "Department management access", "scopeId": "scope_engineering"},
    {"id": "role_team_lead", "name": "Team Lead", "description": "Team leadership access", "scopeId": "scope_platform"}
  ]'
```

### 4. Add Users with Different Access Levels

```bash theme={null}
# Create all users at once with inline memberships and role assignments
curl -X POST 'https://api.example.com/subjects/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "id": "sub_john",
      "subjectType": "user",
      "externalId": "ceo-john",
      "displayName": "John CEO",
      "memberships": [
        {"scopeId": "scope_acme", "roleIds": ["role_org_admin"]}
      ]
    },
    {
      "id": "sub_sarah",
      "subjectType": "user",
      "externalId": "eng-manager-sarah",
      "displayName": "Sarah",
      "memberships": [
        {"scopeId": "scope_engineering", "roleIds": ["role_dept_manager"]}
      ]
    },
    {
      "id": "sub_mike",
      "subjectType": "user",
      "externalId": "dev-mike",
      "displayName": "Mike",
      "memberships": [
        {"scopeId": "scope_platform", "roleIds": ["role_org_member"]}
      ]
    }
  ]'
```

<Info>
  **Inline Memberships**: When creating subjects, you can include `memberships` with `roleIds` to create the subject, membership, and role assignments in a single request.
</Info>

## Common Patterns

### Pattern 1: Multiple Team Membership

Users can belong to multiple teams with different roles:

```bash theme={null}
# Mike is also on the Frontend team with a different role
curl -X POST 'https://api.example.com/memberships' \
  -d '{"subjectId": "sub_mike", "scopeId": "scope_frontend"}'

curl -X POST 'https://api.example.com/role-assignments' \
  -d '{"roleId": "role_team_lead", "membershipId": "mem_mike_frontend"}'
```

### Pattern 2: Restricting Inherited Permissions

Use scope overrides to restrict permissions at child scopes:

```bash theme={null}
# Disable delete permission for the Platform team
curl -X POST 'https://api.example.com/scope-overrides/permissions' \
  -d '{
    "childScopeId": "scope_platform",
    "permissionId": "perm_delete",
    "state": "inactive"
  }'
```

### Pattern 3: Temporary Elevated Access

Assign additional roles for temporary access:

```bash theme={null}
# Give Mike temporary admin access
curl -X POST 'https://api.example.com/role-assignments' \
  -d '{"roleId": "role_team_lead", "membershipId": "mem_mike_platform"}'

# Later, remove the elevated access
curl -X DELETE 'https://api.example.com/role-assignments/role_team_lead/mem_mike_platform'
```

## Memberships and `permissionMode`

Whether access flows down the scope hierarchy depends on the request scope's [`permissionMode`](/concepts/scope-types). Under the default **`override`** mode, Bedrock evaluates a subject's memberships at the **exact scope** of the request—a membership at an override scope does not grant access beneath it:

```
Organization (override)  ─── membership here grants access HERE only
Department   (inherit)   ─── pulls grants from its ancestors
Team         (inherit)   ─── pulls grants from its ancestors
```

Scope types set to **`inherit`** or **`additive`** (like the Department and Team above) **do** draw on ancestor grants.

<Note>
  Under `override`, to give a user access across several scopes, create a membership (and role
  assignment) at **each** scope. Separately, **resource** hierarchies cascade via
  `cascade: 'inherit'` regardless of `permissionMode`. See [Scope Types](/concepts/scope-types),
  [Scopes](/concepts/scopes), and [Evaluation](/concepts/evaluation).
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive role names">
    Name roles based on their function, not the person. Use "Engineering Manager" instead of "Sarah's Role".
  </Accordion>

  <Accordion title="Define permissions at the highest applicable level">
    Create permissions at the organization level if they apply across the organization. This makes them available to all child scopes.
  </Accordion>

  <Accordion title="Use scope overrides sparingly">
    Overrides add complexity. Design your role structure to minimize the need for overrides.
  </Accordion>

  <Accordion title="Audit regularly">
    Periodically review memberships and role assignments to ensure they're still appropriate.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent Governance" icon="robot" href="/guides/agent-governance">
    Apply similar patterns to AI agents
  </Card>

  <Card title="Scope Overrides" icon="sliders" href="/guides/scope-overrides">
    Fine-tune inherited permissions
  </Card>
</CardGroup>