Scope Types

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.

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.

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

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.

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.

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.

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.

Scope-level 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.

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

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

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

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

# 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

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

What is a Scope Type?

Scope Type Properties

Permission Modes

`override` (default)

`inherit`

`additive`

Scope Type Hierarchy

Creating Scope Type Hierarchy

Built-in Scope Types (Bedrock Cloud)

Custom Scope Types

Choosing a Mode

API Reference

Create Scope Type

Create Type Hierarchy

Next Steps

Subjects

​What is a Scope Type?

​Scope Type Properties

​Permission Modes

​override (default)

​inherit

​additive

​Scope Type Hierarchy

​Creating Scope Type Hierarchy

​Built-in Scope Types (Bedrock Cloud)

​Custom Scope Types

​Choosing a Mode

​API Reference

Create Scope Type

Create Type Hierarchy

​Next Steps

Subjects

What is a Scope Type?

Scope Type Properties

Permission Modes

`override` (default)

`inherit`

`additive`

Scope Type Hierarchy

Creating Scope Type Hierarchy

Built-in Scope Types (Bedrock Cloud)

Custom Scope Types

Choosing a Mode

API Reference

Next Steps