User Governance

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

Subjects

Users are registered as subjects with subjectType: "user"

Memberships

Memberships connect users to scopes

Roles

Roles group permissions together

Permissions

Permissions define specific actions

Example: Enterprise Organization

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

1. Define the Hierarchy

# 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

# 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):

# 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

# 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"]}
      ]
    }
  ]'

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

Common Patterns

Pattern 1: Multiple Team Membership

Users can belong to multiple teams with different roles:

# 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:

# 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:

# 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. 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.

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, Scopes, and Evaluation.

Best Practices

Use descriptive role names

Name roles based on their function, not the person. Use “Engineering Manager” instead of “Sarah’s Role”.

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.

Use scope overrides sparingly

Overrides add complexity. Design your role structure to minimize the need for overrides.

Audit regularly

Periodically review memberships and role assignments to ensure they’re still appropriate.

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

User Governance

Overview

Core Concepts

Subjects

Memberships

Roles

Permissions

Example: Enterprise Organization

1. Define the Hierarchy

2. Create Scopes

3. Define Roles at Different Levels

4. Add Users with Different Access Levels

Common Patterns

Pattern 1: Multiple Team Membership

Pattern 2: Restricting Inherited Permissions

Pattern 3: Temporary Elevated Access

Memberships and `permissionMode`

Best Practices

Next Steps

Agent Governance

Scope Overrides

​Overview

​Core Concepts

Subjects

Memberships

Roles

Permissions

​Example: Enterprise Organization

​1. Define the Hierarchy

​2. Create Scopes

​3. Define Roles at Different Levels

​4. Add Users with Different Access Levels

​Common Patterns

​Pattern 1: Multiple Team Membership

​Pattern 2: Restricting Inherited Permissions

​Pattern 3: Temporary Elevated Access

​Memberships and permissionMode

​Best Practices

​Next Steps

Agent Governance

Scope Overrides

Overview

Core Concepts

Example: Enterprise Organization

1. Define the Hierarchy

2. Create Scopes

3. Define Roles at Different Levels

4. Add Users with Different Access Levels

Common Patterns

Pattern 1: Multiple Team Membership

Pattern 2: Restricting Inherited Permissions

Pattern 3: Temporary Elevated Access

Memberships and `permissionMode`

Best Practices

Next Steps