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

# Quickstart

> Set up Bedrock authorization in under 5 minutes

## Overview

This guide walks you through setting up a complete authorization system with Bedrock. By the end, you'll have:

* Scope types defining your organizational hierarchy
* Scopes representing your organization and teams
* Roles and permissions for access control
* A user and an AI agent with appropriate access
* Resource collections for dynamic grouping
* Resource policies that restrict AI agents from confidential data
* Working permission evaluation

<Info>
  **Batch Operations**: All examples use batch endpoints to minimize API calls. IDs use a namespaced UUIDv7 format (e.g., `scope_type_org`). You can provide your own IDs for in-batch references.
</Info>

<Warning>
  **Credentials.** Steps 1–5 are **core control-plane** operations and require a `platform` API key; the `/evaluate` calls in Step 6 require a tenant-scoped `service` key. Both are sent in the **`x-api-key: brk_...`** header (the `brk_YOUR_KEY` placeholder below). Note: `Authorization: Bearer` is the **Kinde user-JWT** path, *not* the API-key path—an API key in a Bearer header returns 401. See [Authentication and Authorization](/api-reference/introduction#authentication-and-authorization).
</Warning>

## Step 1: Set Up Your Hierarchy

Create scope types and their hierarchy relationship in two requests:

```bash theme={null}
# Create all scope types at once
curl -X POST 'https://api.example.com/scope-types/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "scope_type_org", "name": "Organization", "config": {"permissionMode": "override"}},
    {"id": "scope_type_team", "name": "Team", "config": {"permissionMode": "inherit"}}
  ]'

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

## Step 2: Create Your Organization Structure

Create scopes and link them in the hierarchy:

```bash theme={null}
# Create organization and team scopes
curl -X POST 'https://api.example.com/scopes/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "scope_acme", "typeId": "scope_type_org", "name": "Acme Corp", "externalId": "acme-corp"},
    {"id": "scope_engineering", "typeId": "scope_type_team", "name": "Engineering", "externalId": "engineering"}
  ]'

# Link team to organization
curl -X POST 'https://api.example.com/scope-hierarchy/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[{"parentScopeId": "scope_acme", "childScopeId": "scope_engineering"}]'
```

## Step 3: Define Roles and Permissions

Create permissions and roles, then assign permissions to roles:

```bash theme={null}
# Create permissions
curl -X POST 'https://api.example.com/permissions/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "permission_read", "scopeId": "scope_acme", "action": "read", "resourceType": "document", "resourcePattern": "*", "key": "document:read:*", "label": "Read Documents"},
    {"id": "permission_write", "scopeId": "scope_acme", "action": "write", "resourceType": "document", "resourcePattern": "*", "key": "document:write:*", "label": "Write Documents"},
    {"id": "permission_delete", "scopeId": "scope_acme", "action": "delete", "resourceType": "document", "resourcePattern": "*", "key": "document:delete:*", "label": "Delete Documents"}
  ]'

# Create roles
curl -X POST 'https://api.example.com/roles/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "role_viewer", "name": "Viewer", "description": "Read-only access", "scopeId": "scope_acme"},
    {"id": "role_editor", "name": "Editor", "description": "Can read and write", "scopeId": "scope_acme"}
  ]'

# Assign permissions to roles
curl -X POST 'https://api.example.com/role-permissions/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {"roleId": "role_viewer", "permissionId": "permission_read"},
    {"roleId": "role_editor", "permissionId": "permission_read"},
    {"roleId": "role_editor", "permissionId": "permission_write"}
  ]'
```

## Step 4: Add Users and Agents

Create subjects (user and AI agent), memberships, and role assignments:

```bash theme={null}
# Create subjects: a user and an AI agent
curl -X POST 'https://api.example.com/subjects/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "id": "subject_jane",
      "subjectType": "user",
      "externalId": "user-jane-doe",
      "displayName": "Jane Doe",
      "meta": {"email": "jane@acme.com"}
    },
    {
      "id": "subject_agent",
      "subjectType": "agent",
      "externalId": "coding-assistant-v1",
      "displayName": "Coding Assistant",
      "meta": {"model": "claude-3"}
    }
  ]'

# Add both to engineering team
curl -X POST 'https://api.example.com/memberships/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "membership_jane_eng", "subjectId": "subject_jane", "scopeId": "scope_engineering"},
    {"id": "membership_agent_eng", "subjectId": "subject_agent", "scopeId": "scope_engineering"}
  ]'

# Assign roles: Editor for Jane, Viewer for the agent
curl -X POST 'https://api.example.com/role-assignments/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {"roleId": "role_editor", "membershipId": "membership_jane_eng"},
    {"roleId": "role_viewer", "membershipId": "membership_agent_eng"}
  ]'
```

<Check>
  You now have a user with Editor access and an AI agent with Viewer access to the Engineering team!
</Check>

## Step 5: Add Resources and Policies

Create resources, a collection, and a policy for fine-grained control:

```bash theme={null}
# Create a resource type and some resources
curl -X POST 'https://api.example.com/resource-types/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "rtype_document", "name": "Document", "scopeId": "scope_acme"}
  ]'

curl -X POST 'https://api.example.com/resources/batch' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "resource_roadmap", "resourceTypeId": "rtype_document", "ownerScopeId": "scope_engineering", "externalResourceId": "roadmap-2024", "displayName": "2024 Roadmap"},
    {"id": "resource_budget", "resourceTypeId": "rtype_document", "ownerScopeId": "scope_engineering", "externalResourceId": "budget-confidential", "displayName": "Budget (Confidential)"}
  ]'

# Create a tag group with a "confidential" tag (tags live in a group; use identifier/label)
curl -X POST 'https://api.example.com/tag-groups' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"id": "tg_classification", "scopeId": "scope_acme", "name": "Classification", "key": "classification", "tags": [{"id": "tag_confidential", "identifier": "confidential", "label": "Confidential"}]}'

# Tag the budget document (assignment uses targetType/targetId)
curl -X POST 'https://api.example.com/tag-assignments' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"tagId": "tag_confidential", "targetType": "resource", "targetId": "resource_budget"}'

# Create a collection for confidential documents
curl -X POST 'https://api.example.com/resource-collections' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "collection_confidential",
    "scopeId": "scope_acme",
    "resourceTypeId": "rtype_document",
    "name": "Confidential Documents",
    "match": {
      "tags": {"confidential": "Confidential"}
    }
  }'

# Create a policy: deny agents access to confidential documents
curl -X POST 'https://api.example.com/resource-policies' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "policy_no_agent_confidential",
    "scopeId": "scope_acme",
    "name": "Block Agents from Confidential",
    "target": {
      "kind": "collection",
      "collectionId": "collection_confidential"
    },
    "actions": ["*"],
    "effect": "deny",
    "priority": 100,
    "subjectCondition": {
      "==": [{"var": "subject.subjectType"}, "agent"]
    }
  }'
```

## Step 6: Evaluate Permissions

Test your authorization setup:

```bash theme={null}
# Jane can read the roadmap
curl -X POST 'https://api.example.com/evaluate' \
  -H 'x-api-key: brk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "actor": {"subjectId": "subject_jane", "subjectType": "user"},
    "scopeId": "scope_engineering",
    "action": "read",
    "resource": {"resourceId": "resource_roadmap"}
  }'
# → {"allowed": true, "explanation": "Allowed via role Editor..."}

# Jane can read the confidential budget
curl -X POST 'https://api.example.com/evaluate' \
  -d '{
    "actor": {"subjectId": "subject_jane", "subjectType": "user"},
    "scopeId": "scope_engineering",
    "action": "read",
    "resource": {"resourceId": "resource_budget"}
  }'
# → {"allowed": true}

# Agent CANNOT read the confidential budget (blocked by policy)
curl -X POST 'https://api.example.com/evaluate' \
  -d '{
    "actor": {"subjectId": "subject_agent", "subjectType": "agent"},
    "scopeId": "scope_engineering",
    "action": "read",
    "resource": {"resourceId": "resource_budget"}
  }'
# → {"allowed": false, "decidedByPolicy": true, "explanation": "Denied by policy: Block Agents from Confidential"}

# Agent CAN read the non-confidential roadmap
curl -X POST 'https://api.example.com/evaluate' \
  -d '{
    "actor": {"subjectId": "subject_agent", "subjectType": "agent"},
    "scopeId": "scope_engineering",
    "action": "read",
    "resource": {"resourceId": "resource_roadmap"}
  }'
# → {"allowed": true}
```

<Check>
  **Done!** You've set up a complete authorization system with role-based permissions AND resource-level policies that restrict AI agents from accessing confidential documents.
</Check>

## What You Built

```
Acme Corp (Organization)
├── Roles: Viewer (read), Editor (read, write)
├── Collection: Confidential Documents (tag: classification=confidential)
├── Policy: Block Agents from Confidential
│
└── Engineering (Team)
    ├── Jane Doe (User) → Editor → can read/write all documents
    ├── Coding Assistant (Agent) → Viewer → can read non-confidential only
    │
    ├── 2024 Roadmap (Document) → accessible to all
    └── Budget (Document, confidential) → blocked for agents
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Resource Policies" icon="shield-check" href="/resources/resource-policies">
    Fine-grained allow/deny on resources
  </Card>

  <Card title="Resource Collections" icon="layer-group" href="/resources/resource-collections">
    Dynamic resource grouping
  </Card>

  <Card title="Conditional Permissions" icon="code" href="/concepts/conditional-permissions">
    JSON Logic for dynamic access
  </Card>

  <Card title="Agent Governance" icon="robot" href="/guides/agent-governance">
    Advanced agent permission patterns
  </Card>

  <Card title="Scope Overrides" icon="sliders" href="/concepts/overrides">
    Fine-tune inherited permissions
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Explore the complete API
  </Card>
</CardGroup>