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

# Scopes

> Hierarchical containers that define authorization boundaries

## 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`](/concepts/scope-types): 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

```bash theme={null}
# 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

```bash theme={null}
# 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`](/concepts/scope-types).

**`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](/concepts/scope-types).

<Note>
  Membership composition is one axis. **Resource hierarchy** (`cascade: 'inherit'`) and **scope overrides** traverse ancestors independently of `permissionMode`. See [Evaluation](/concepts/evaluation) and [Scope Overrides](/concepts/overrides).
</Note>

## Scope-Specific Roles

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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Create Scope" icon="plus" href="/api-reference/scopes/create-scope">
    Create a new scope
  </Card>

  <Card title="Get Scope Children" icon="sitemap" href="/api-reference/scopes/get-scope-children">
    Get child scopes
  </Card>

  <Card title="Create Hierarchy Edge" icon="link" href="/api-reference/scope-hierarchy/create-edge">
    Link scopes in hierarchy
  </Card>

  <Card title="All Scope Endpoints" icon="list" href="/api-reference/scopes/get-scopes">
    View all scope operations
  </Card>
</CardGroup>

## Next Steps

<Card title="Scope Types" icon="arrow-right" href="/concepts/scope-types">
  Learn how scope types define the rules for your hierarchy
</Card>