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

# Scope Types

> Templates that define how scopes behave and compose permissions across the hierarchy

## What is a Scope Type?

A **scope type** is a template that defines the behavior of scopes. Think of scope types as "classes" and scopes as "instances"—every scope has a type, and the type determines **how the engine resolves a subject's permissions across the scope hierarchy** when a request is evaluated at that scope.

## Scope Type Properties

| Property                      | Type                                    | Description                                                                             |
| ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------- |
| `id`                          | `string`                                | Unique identifier                                                                       |
| `name`                        | `string`                                | Human-readable name (e.g., "Organization", "Team", "Project")                           |
| `parentTypeId`                | `string?`                               | Optional parent type — constrains which types may contain which                         |
| `config.permissionMode`       | `'inherit' \| 'override' \| 'additive'` | How permissions compose across the scope chain (see below). **Defaults to `override`.** |
| `config.canDefinePermissions` | `boolean`                               | Whether scopes of this type may define their own permissions (default `false`)          |
| `config.canDefineRoles`       | `boolean`                               | Whether scopes of this type may define their own roles (default `true`)                 |

## Permission Modes

`config.permissionMode` controls **whether a scope pulls in a subject's grants from its ancestor scopes** when the engine evaluates a request. There are exactly three modes: `override`, `inherit`, and `additive`.

<Note>
  The mode is a property of the scope being **evaluated**. When you call `evaluate` with a `scopeId`, the engine reads *that scope's* type's `permissionMode` to decide whether to look only at that scope or also walk up its parent chain. If a scope or its type is missing a mode, the engine defaults to `override`.
</Note>

### `override` (default)

A subject's grants are resolved **at the request scope only**. Ancestor scopes are not consulted, so a subject must have a membership *at that exact scope* to be granted anything there.

This is the **default**—used whenever a scope or type has no explicit mode—and the most isolated. Use it for boundaries you don't want authority to cross.

```bash theme={null}
curl -X POST 'https://api.example.com/scope-types' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Organization",
    "config": {"permissionMode": "override"}
  }'
```

**Use cases:** tenant roots, isolated business units, compliance boundaries.

### `inherit`

If the request scope has **no grants** for the subject, the engine falls back to the **nearest ancestor** scope (walking up the parent chain) that does. Nearest-non-empty wins: this is a *fallback*, not a merge—once a scope with grants is found, scopes further up are not added.

```bash theme={null}
curl -X POST 'https://api.example.com/scope-types' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Team",
    "config": {"permissionMode": "inherit"}
  }'
```

**Use cases:** deep hierarchies where a role assigned at a mid-level scope should apply to everything beneath it, without re-assigning at every level.

### `additive`

A subject's grants at the request scope **and all ancestor scopes** are combined (union, de-duplicated by role and permission). A role held anywhere up the chain contributes its permissions at the request scope.

```bash theme={null}
curl -X POST 'https://api.example.com/scope-types' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Project",
    "config": {"permissionMode": "additive"}
  }'
```

**Use cases:** organizations where permissions accumulate downward—an Editor at the workspace is also an Editor in every project and environment beneath it, in addition to any scope-specific grants.

<Warning>
  Under **`override` (the default), a role assigned at a *parent* scope does NOT apply to child scopes.** Permissions flow down the hierarchy **only** under `inherit` or `additive`. If you expect an org-level role to reach child scopes, the child scope's type must use `inherit` or `additive`.
</Warning>

<Note>
  Scope-level [overrides](/concepts/overrides) (disabling a role or permission, or revoking/granting a role-permission edge at a specific scope) are always applied on top of the composed grants—including the request scope's own overrides under `inherit`/`additive`.
</Note>

## Scope Type Hierarchy

Scope types form their own hierarchy that defines **which types can contain which**. This is separate from the scope hierarchy itself.

```
Organization
    │
    └── can contain ──▶ Team
                            │
                            └── can contain ──▶ Project
                                                    │
                                                    └── can contain ──▶ Environment
```

### Creating Scope Type Hierarchy

```bash theme={null}
# Define that Teams can be children of Organizations
curl -X POST 'https://api.example.com/scope-type-hierarchy' \
  -H 'Content-Type: application/json' \
  -d '{
    "parentTypeId": "scope_type_org",
    "childTypeId": "scope_type_team"
  }'

# Define that Projects can be children of Teams
curl -X POST 'https://api.example.com/scope-type-hierarchy' \
  -d '{
    "parentTypeId": "scope_type_team",
    "childTypeId": "scope_type_project"
  }'
```

<Note>
  The scope type hierarchy enforces structural rules. You cannot create a scope hierarchy edge that violates the type hierarchy.
</Note>

## Built-in Scope Types (Bedrock Cloud)

The hosted platform provisions a default set of scope types via its bootstrap policy, forming the multi-tenant control plane:

```
Tenant
└── Workspace
    └── Project
        └── Environment
```

The permission mode for each of these is set by the platform bootstrap policy. Confirm the exact modes in your deployment's platform configuration rather than assuming—do not rely on a specific mode here without verifying it against the seeded policy.

## Custom Scope Types

You can create custom scope types to match your domain. Pick each type's `permissionMode` based on whether scopes of that type should isolate (`override`) or draw authority from their ancestors (`inherit` / `additive`):

```bash theme={null}
# Create custom scope types for a construction company.
# The company root isolates (override); everything beneath accumulates (additive).
curl -X POST 'https://api.example.com/scope-types/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "type_company",  "name": "Company",  "config": {"permissionMode": "override"}},
    {"id": "type_division", "name": "Division", "config": {"permissionMode": "additive"}},
    {"id": "type_jobsite",  "name": "Job Site", "config": {"permissionMode": "additive"}},
    {"id": "type_crew",     "name": "Crew",     "config": {"permissionMode": "additive"}}
  ]'

# Define the hierarchy
curl -X POST 'https://api.example.com/scope-type-hierarchy/batch' \
  -d '[
    {"parentTypeId": "type_company",  "childTypeId": "type_division"},
    {"parentTypeId": "type_division", "childTypeId": "type_jobsite"},
    {"parentTypeId": "type_jobsite",  "childTypeId": "type_crew"}
  ]'
```

## Choosing a Mode

| Scenario                                              | Mode       | Reason                                              |
| ----------------------------------------------------- | ---------- | --------------------------------------------------- |
| Isolated boundary (tenant root, compliance)           | `override` | Grants never cross the boundary                     |
| A role assigned mid-hierarchy should apply beneath it | `inherit`  | Nearest ancestor with grants is used as a fallback  |
| Permissions accumulate down the tree                  | `additive` | Union of the scope's grants and all ancestor grants |

## API Reference

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

  <Card title="Create Type Hierarchy" icon="link" href="/api-reference/scope-type-hierarchy/create-edge">
    Define parent-child type relationships
  </Card>
</CardGroup>

## Next Steps

<Card title="Subjects" icon="arrow-right" href="/concepts/subjects">
  Learn about the entities that receive permissions
</Card>