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

# Introduction

> Bedrock API Reference - Authorization and Access Control Management

## Welcome

The Bedrock API provides a comprehensive authorization and access control system. It enables you to manage subjects (users, API keys, services, agents), scopes (organizational hierarchies), roles, permissions, resources, tags, and fine-grained access control through overrides.

## ID Format

All entity IDs use a **namespaced UUIDv7** format for easy identification and sorting:

```
{namespace}_{uuidv7}
```

| Namespace       | Entity                         |
| --------------- | ------------------------------ |
| `subject`       | Subjects (users, agents, etc.) |
| `scope`         | Scopes                         |
| `scope_type`    | Scope Types                    |
| `role`          | Roles                          |
| `permission`    | Permissions                    |
| `resource`      | Resources                      |
| `resource_type` | Resource Types                 |
| `tag`           | Tags                           |
| `tag_group`     | Tag Groups                     |

<Tip>
  You can provide your own IDs when creating entities. This is useful for batch operations where you need to reference entities within the same request.
</Tip>

## Core Concepts

<CardGroup cols={2}>
  <Card title="Subjects" icon="user" href="/api-reference/subjects/get-subject">
    Users, API keys, services, or agents that can be granted access
  </Card>

  <Card title="Scopes" icon="sitemap" href="/api-reference/scopes/get-scope">
    Hierarchical organizational units (orgs, teams, projects)
  </Card>

  <Card title="Roles" icon="user-shield" href="/api-reference/roles/get-role">
    Named collections of permissions assignable to memberships
  </Card>

  <Card title="Permissions" icon="key" href="/api-reference/permissions/get-permission">
    Granular access rights (e.g., read:documents, write:documents)
  </Card>

  <Card title="Resources" icon="file" href="/api-reference/resources/create-resource">
    Protected objects with types and hierarchies
  </Card>

  <Card title="Tags" icon="tag" href="/api-reference/tags/create-tag">
    Flexible metadata and categorization
  </Card>
</CardGroup>

## How It Works

1. **Subjects** are added to **Scopes** via **Memberships**
2. **Roles** are assigned to **Memberships** via **Role Assignments**
3. **Permissions** are assigned to **Roles** via **Role Permissions**
4. **Resources** are created within **Scopes** with **Resource Types**
5. **Tags** can be applied to resources, subjects, and other entities
6. **Scope Overrides** allow fine-tuning inherited roles/permissions at child scopes

## Batch Operations

Most create endpoints support batch operations via a `/batch` suffix. Batch requests:

* Accept an array of objects
* Support client-provided IDs for in-batch references
* Validate ID uniqueness within the batch
* Return an array of created entities

```bash theme={null}
# Example: Create multiple scopes in one request
curl -X POST 'https://api.example.com/scopes/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "scope_org", "typeId": "scope_type_org", "name": "Acme"},
    {"id": "scope_team", "typeId": "scope_type_team", "name": "Engineering"}
  ]'
```

## Authentication and Authorization

Programmatic clients authenticate with a **Bedrock API key** sent in the `x-api-key` header (the Bedrock console authenticates human users via session):

```bash theme={null}
curl -X POST 'https://api.example.com/evaluate' \
  -H 'x-api-key: brk_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{ "actor": { "subjectId": "subject_jane", "subjectType": "user" }, "scopeId": "scope_engineering", "action": "read", "resource": { "resourceId": "resource_roadmap" } }'
```

Every API key carries a **`kind`** that determines which API surfaces it may reach:

| `kind`             | Reaches                                                                                                           | Scope                   |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `user` *(default)* | Management actions as that subject                                                                                | tenant-scoped           |
| `service`          | **Decision path** — `POST /evaluate`, `GET /effective-permissions` (may assert any subject **within its tenant**) | tenant-scoped           |
| `platform`         | **Core control-plane** — roles, permissions, scopes, resources, policies, tags, subjects, memberships, overrides  | operator (cross-tenant) |

* The **core control-plane endpoints require a `platform` key** — a `user`/`service` key receives `403`.
* The **decision path requires a `service` (or `platform`) key**, and a `service` key may only evaluate **within its own tenant's scopes** — a request whose `scopeId` belongs to another tenant receives `403`.
* A negative authorization *decision* from `/evaluate` is still `200` with `{ "allowed": false }`. The `401`/`403` responses are only about whether the caller's **key may use the endpoint at all** — they are distinct from the decision result.

<Warning>
  **Upgrading existing keys.** API keys created before credential tiers existed default to `kind: user` (least privilege). If you use an existing key for programmatic `/evaluate` calls or core control-plane operations, **re-mint it as a `service` or `platform` key** — otherwise those requests now return `403`.
</Warning>

## Base URL

```
https://api.example.com
```

## API Groups

### Core Authorization

| Group                    | Description                                          |
| ------------------------ | ---------------------------------------------------- |
| **Subjects**             | Manage users, API keys, services, and agents         |
| **Memberships**          | Add/remove subjects from scopes                      |
| **Roles**                | Define roles within scopes                           |
| **Role Assignments**     | Assign roles to memberships                          |
| **Permissions**          | Define permissions within scopes                     |
| **Role Permissions**     | Map permissions to roles                             |
| **Scopes**               | Manage organizational hierarchy nodes                |
| **Scope Types**          | Define types of scopes (org, team, project)          |
| **Scope Hierarchy**      | Manage parent-child scope relationships              |
| **Scope Type Hierarchy** | Define valid type relationships                      |
| **Scope Overrides**      | Override inherited roles/permissions at child scopes |
| **Resource Types**       | Define categories of protected resources             |
| **Resources**            | Manage protected objects within scopes               |

### Tags & Classification

| Group               | Description                                   |
| ------------------- | --------------------------------------------- |
| **Tag Groups**      | Define categories of tags                     |
| **Tags**            | Create tags within groups                     |
| **Tag Bindings**    | Control which models can use which tag groups |
| **Tag Assignments** | Assign tags to resources, subjects, etc.      |

### Management Models (Bedrock Cloud)

| Group            | Description                                |
| ---------------- | ------------------------------------------ |
| **Tenants**      | Customer accounts with billing and limits  |
| **Workspaces**   | Logical groupings within tenants           |
| **Projects**     | Applications or services within workspaces |
| **Environments** | Deployment stages (prod, staging, dev)     |
| **Users**        | Human users with IDP integration           |
| **API Keys**     | Programmatic access credentials            |