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

> Fine-tuning inherited permissions at specific scopes

## Overview

Scope overrides allow you to modify inherited permissions at specific points in your scope hierarchy. This enables fine-grained control without restructuring your entire role and permission model.

## Types of Overrides

Bedrock supports three types of overrides:

| Override Type                | What it Controls                                               | Use Case                                         |
| ---------------------------- | -------------------------------------------------------------- | ------------------------------------------------ |
| **Role Override**            | `active` / `inactive` an entire role at a scope                | Deactivate "Admin" in production                 |
| **Permission Override**      | `active` / `inactive` a specific permission at a scope         | Deactivate "delete" in compliance areas          |
| **Role-Permission Override** | `grant` / `revoke` a permission for a specific role at a scope | Revoke "write" for "Editor" in archived projects |

## How Overrides Work

Overrides are applied **per scope** during grant resolution:

```
1. Resolve the subject's grants at the request scope (per its permissionMode)
2. Apply THAT scope's overrides (role active/inactive, permission active/inactive,
   role-permission grant/revoke)
3. Return the effective grants
```

<Note>
  Overrides are per-scope, **not** a top-down cascade: an override set at a parent scope does
  not automatically apply to children evaluated under the default `override` mode. A
  role-permission `grant` can add a grant for a role the subject already holds; `revoke`/
  `inactive` remove grants. See [Scope Overrides](/concepts/overrides) for the full model.
</Note>

## Role Overrides

Disable or enable an entire role at a specific scope.

### Example: Disable Admin Role in Production

```bash theme={null}
# Admin role is defined at org level
curl -X POST 'https://api.example.com/roles' \
  -d '{
    "name": "Admin",
    "description": "Full administrative access",
    "scopeId": "scope_org"
  }'

# Disable Admin role in production scope
curl -X POST 'https://api.example.com/scope-overrides/roles' \
  -H 'Content-Type: application/json' \
  -d '{
    "childScopeId": "scope_production",
    "roleId": "role_admin",
    "state": "inactive"
  }'
```

Now users with the Admin role won't have admin access in the production scope.

### Updating Role Overrides

```bash theme={null}
# Re-activate the role
curl -X PUT 'https://api.example.com/scope-overrides/roles/override_123' \
  -d '{"state": "active"}'
```

## Permission Overrides

Disable or enable a specific permission at a scope.

### Example: Disable Delete Permission in Compliance Scope

```bash theme={null}
# Delete permission exists at org level
curl -X POST 'https://api.example.com/permissions' \
  -d '{"scopeId": "scope_org", "action": "delete", "resourceType": "record", "resourcePattern": "*", "key": "record:delete:*"}'

# Disable delete in compliance scope
curl -X POST 'https://api.example.com/scope-overrides/permissions' \
  -d '{
    "childScopeId": "scope_compliance",
    "permissionId": "perm_delete_records",
    "state": "inactive"
  }'
```

### Example: Disable Code Execution for All Agents

```bash theme={null}
# Disable execute permission in production
curl -X POST 'https://api.example.com/scope-overrides/permissions' \
  -d '{
    "childScopeId": "scope_production",
    "permissionId": "perm_execute_code",
    "state": "inactive"
  }'
```

## Role-Permission Overrides

The most granular override: disable a specific permission for a specific role at a specific scope.

### Example: Editors Can't Delete in Archived Projects

```bash theme={null}
# Editor role has delete permission at org level
curl -X POST 'https://api.example.com/role-permissions' \
  -d '{"roleId": "role_editor", "permissionId": "perm_delete"}'

# But not in archived projects
curl -X POST 'https://api.example.com/scope-overrides/role-permissions' \
  -d '{
    "childScopeId": "scope_archived_projects",
    "roleId": "role_editor",
    "permissionId": "perm_delete",
    "state": "revoke"
  }'
```

### Example: Agents Can Read But Not Write in Sensitive Areas

```bash theme={null}
# Agent role has both read and write
curl -X POST 'https://api.example.com/role-permissions' \
  -d '{"roleId": "role_agent_writer", "permissionId": "perm_read"}'

curl -X POST 'https://api.example.com/role-permissions' \
  -d '{"roleId": "role_agent_writer", "permissionId": "perm_write"}'

# Disable write for this role in customer data scope
curl -X POST 'https://api.example.com/scope-overrides/role-permissions' \
  -d '{
    "childScopeId": "scope_customer_data",
    "roleId": "role_agent_writer",
    "permissionId": "perm_write",
    "state": "revoke"
  }'
```

## Overrides Are Per-Scope

Overrides are applied at the scope where they are set—there is **no** cross-scope "most specific wins" precedence and **no** automatic top-down cascade. Under the default `override` `permissionMode`, only the request scope's own overrides apply; under `inherit`/`additive`, each scope's overrides apply to that scope's grants as they compose. To restrict at multiple scopes, set the override at each. See [Scope Overrides](/concepts/overrides) and [Scope Types](/concepts/scope-types).

## Viewing Overrides

### Get All Overrides for a Scope

```bash theme={null}
# Role overrides
curl -X GET 'https://api.example.com/scope-overrides/roles/scope_production'

# Permission overrides
curl -X GET 'https://api.example.com/scope-overrides/permissions/scope_production'

# Role-permission overrides
curl -X GET 'https://api.example.com/scope-overrides/role-permissions/scope_production'
```

## Deleting Overrides

```bash theme={null}
# Delete by ID
curl -X DELETE 'https://api.example.com/scope-overrides/roles/override_123'

# Delete by scope and role
curl -X DELETE 'https://api.example.com/scope-overrides/roles/scope_production/role_admin'

# Delete role-permission override by all IDs
curl -X DELETE 'https://api.example.com/scope-overrides/role-permissions/scope_production/role_editor/perm_delete'
```

## Common Patterns

### Pattern 1: Production Lockdown

Restrict dangerous operations in production:

```bash theme={null}
# Disable multiple destructive permissions at once
curl -X POST 'https://api.example.com/scope-overrides/permissions/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"childScopeId": "scope_prod", "permissionId": "perm_delete", "state": "inactive"},
    {"childScopeId": "scope_prod", "permissionId": "perm_execute", "state": "inactive"},
    {"childScopeId": "scope_prod", "permissionId": "perm_modify_infra", "state": "inactive"}
  ]'
```

### Pattern 2: Agent Sandboxing

Restrict agent capabilities in sensitive areas:

```bash theme={null}
# Batch restrict agent permissions in sensitive scopes
curl -X POST 'https://api.example.com/scope-overrides/role-permissions/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"childScopeId": "scope_customer_data", "roleId": "role_agent", "permissionId": "perm_write", "state": "revoke"},
    {"childScopeId": "scope_pii", "roleId": "role_agent", "permissionId": "perm_read", "state": "revoke"}
  ]'
```

### Pattern 3: Temporary Restrictions

Apply temporary restrictions during incidents:

```bash theme={null}
# During incident: disable all writes
curl -X POST 'https://api.example.com/scope-overrides/permissions' \
  -d '{
    "childScopeId": "scope_affected_service",
    "permissionId": "perm_write",
    "state": "inactive"
  }'

# After incident: remove override
curl -X DELETE 'https://api.example.com/scope-overrides/permissions/scope_affected_service/perm_write'
```

### Pattern 4: Compliance Zones

Create compliance zones with restricted access:

```bash theme={null}
# Set up multiple compliance zones at once
curl -X POST 'https://api.example.com/scope-overrides/permissions/batch' \
  -H 'Content-Type: application/json' \
  -d '[
    {"childScopeId": "scope_soc2", "permissionId": "perm_export_data", "state": "inactive"},
    {"childScopeId": "scope_hipaa", "permissionId": "perm_share_external", "state": "inactive"},
    {"childScopeId": "scope_hipaa", "permissionId": "perm_export_data", "state": "inactive"}
  ]'
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use overrides sparingly">
    Too many overrides make the system hard to understand. Prefer restructuring roles when possible.
  </Accordion>

  <Accordion title="Document your overrides">
    Keep a record of why each override exists and when it should be reviewed.
  </Accordion>

  <Accordion title="Prefer permission overrides over role overrides">
    Permission overrides are more granular and less likely to have unintended effects.
  </Accordion>

  <Accordion title="Test override effects">
    Before applying overrides in production, test in a staging environment.
  </Accordion>

  <Accordion title="Audit override changes">
    Log all override creations, updates, and deletions for compliance.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="User Governance" icon="user-shield" href="/guides/user-governance">
    Apply overrides to user permissions
  </Card>

  <Card title="Agent Governance" icon="robot" href="/guides/agent-governance">
    Apply overrides to agent permissions
  </Card>
</CardGroup>