Scopes

What is a Scope?

A scope is a container that defines an authorization boundary. Scopes form a hierarchy—like folders in a file system. Whether a subject’s grants flow down that hierarchy is controlled by each scope type’s permissionMode: under the default override mode a membership is evaluated at exactly the scope you ask about, while inherit and additive compose grants up the ancestor chain. The hierarchy is also used for cascading scope overrides and for resource inheritance. Every authorization decision in Bedrock happens within a scope context.

Scope Properties

Property	Type	Description
`id`	`string`	Unique identifier
`typeId`	`string`	Reference to the scope type
`externalId`	`string?`	Your system’s identifier for this scope
`name`	`string?`	Human-readable name
`meta`	`Record<string, unknown>?`	Custom metadata

Scope Hierarchy

Scopes connect to form a tree structure via hierarchy edges:

Acme Corp (Organization)
├── Engineering (Team)
│   ├── Backend (Project)
│   │   ├── Production (Environment)
│   │   └── Staging (Environment)
│   └── Frontend (Project)
│       └── Production (Environment)
└── Sales (Team)
    └── CRM (Project)
        └── Production (Environment)

Creating Hierarchy Edges

# Create parent-child relationship
curl -X POST 'https://api.example.com/scope-hierarchy' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "parentScopeId": "scope_acme",
    "childScopeId": "scope_engineering"
  }'

Querying the Hierarchy

# Get children of a scope
curl -X GET 'https://api.example.com/scopes/scope_acme/children'

# Get parents of a scope
curl -X GET 'https://api.example.com/scopes/scope_engineering/parents'

Membership and `permissionMode`

How a subject’s memberships combine across the hierarchy is governed by the request scope’s permissionMode. override (the default). Bedrock looks up the subject’s memberships at exactly the requested scope—it does not walk up the hierarchy. A role granted at a parent scope does not apply at child scopes:

Organization ─── Subject has "Editor" membership here
    │
    ├── Team A ─── NO access (no membership at this scope)
    │   │
    │   └── Project X ─── NO access (no membership at this scope)
    │
    └── Team B ─── NO access (no membership at this scope)

Under override, to grant a subject access across multiple scopes you create a membership (and role assignment) at each scope where access is needed—granular, per-location control, so holding a role at an organization does not silently grant the same power beneath it. inherit / additive. Scopes whose type uses these modes do draw on ancestor grants: inherit falls back to the nearest ancestor that has grants, and additive unions the scope’s grants with all ancestors. A role held at a parent scope then reaches descendants of that type. Choose the mode per scope type—see Scope Types.

Membership composition is one axis. Resource hierarchy (cascade: 'inherit') and scope overrides traverse ancestors independently of permissionMode. See Evaluation and Scope Overrides.

Scope-Specific Roles

Roles are defined at a specific scope and can be used in that scope and its descendants:

# Create a role at the organization level
curl -X POST 'https://api.example.com/roles' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Editor",
    "description": "Can read and write documents",
    "scopeId": "scope_acme"
  }'

This “Editor” role can now be assigned to memberships in:

scope_acme (where it’s defined)
Any descendant scope (teams, projects, environments)

Scope-Specific Permissions

Permissions are also scoped. A permission defined at a parent scope is available to roles in that scope and all descendants:

# Create a permission at the organization level
curl -X POST 'https://api.example.com/permissions' \
  -H 'Content-Type: application/json' \
  -d '{
    "scopeId": "scope_acme",
    "action": "write",
    "resourceType": "document",
    "resourcePattern": "*",
    "key": "document:write:*",
    "label": "Write Documents"
  }'

External IDs

Use externalId to map Bedrock scopes to entities in your system:

# Create scope with external ID
curl -X POST 'https://api.example.com/scopes' \
  -d '{
    "typeId": "scope_type_project",
    "name": "Backend API",
    "externalId": "project-123"
  }'

# Later, look up by external ID
curl -X GET 'https://api.example.com/scopes?externalId=project-123'

Scope Metadata

Store custom data on scopes using the meta field:

curl -X POST 'https://api.example.com/scopes' \
  -d '{
    "typeId": "scope_type_project",
    "name": "Backend API",
    "meta": {
      "region": "us-east-1",
      "costCenter": "engineering",
      "compliance": ["soc2", "hipaa"]
    }
  }'

Metadata can be used in conditional permission logic.

Common Patterns

Pattern 1: Multi-Tenant Isolation

Each tenant gets its own scope tree:

Platform (root)
├── Tenant A (Organization)
│   └── ... (Tenant A's hierarchy)
└── Tenant B (Organization)
    └── ... (Tenant B's hierarchy)

Pattern 2: Environment Separation

Separate permissions by environment:

Project
├── Production (strict permissions)
├── Staging (relaxed permissions)
└── Development (open permissions)

Pattern 3: Department-Based Access

Organize by organizational structure:

Company
├── Engineering
│   ├── Backend Team
│   └── Frontend Team
├── Sales
│   ├── Enterprise
│   └── SMB
└── Finance
    └── Accounting

API Reference

Create Scope

Create a new scope

Get Scope Children

Get child scopes

Create Hierarchy Edge

Link scopes in hierarchy

All Scope Endpoints

View all scope operations

Next Steps

Scope Types

Learn how scope types define the rules for your hierarchy

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

What is a Scope?

Scope Properties

Scope Hierarchy

Creating Hierarchy Edges

Querying the Hierarchy

Membership and `permissionMode`

Scope-Specific Roles

Scope-Specific Permissions

External IDs

Scope Metadata

Common Patterns

Pattern 1: Multi-Tenant Isolation

Pattern 2: Environment Separation

Pattern 3: Department-Based Access

API Reference

Create Scope

Get Scope Children

Create Hierarchy Edge

All Scope Endpoints

Next Steps

Scope Types

​What is a Scope?

​Scope Properties

​Scope Hierarchy

​Creating Hierarchy Edges

​Querying the Hierarchy

​Membership and permissionMode

​Scope-Specific Roles

​Scope-Specific Permissions

​External IDs

​Scope Metadata

​Common Patterns

​Pattern 1: Multi-Tenant Isolation

​Pattern 2: Environment Separation

​Pattern 3: Department-Based Access

​API Reference

Create Scope

Get Scope Children

Create Hierarchy Edge

All Scope Endpoints

​Next Steps

Scope Types

What is a Scope?

Scope Properties

Scope Hierarchy

Creating Hierarchy Edges

Querying the Hierarchy

Membership and `permissionMode`

Scope-Specific Roles

Scope-Specific Permissions

External IDs

Scope Metadata

Common Patterns

Pattern 1: Multi-Tenant Isolation

Pattern 2: Environment Separation

Pattern 3: Department-Based Access

API Reference

Next Steps