Quickstart

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

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.

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.

Step 1: Set Up Your Hierarchy

Create scope types and their hierarchy relationship in two requests:

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

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

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

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

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

Step 5: Add Resources and Policies

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

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

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

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.

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

Resource Policies

Fine-grained allow/deny on resources

Resource Collections

Dynamic resource grouping

Conditional Permissions

JSON Logic for dynamic access

Agent Governance

Advanced agent permission patterns

Scope Overrides

Fine-tune inherited permissions

API Reference

Explore the complete API

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

Overview

Step 1: Set Up Your Hierarchy

Step 2: Create Your Organization Structure

Step 3: Define Roles and Permissions

Step 4: Add Users and Agents

Step 5: Add Resources and Policies

Step 6: Evaluate Permissions

What You Built

Next Steps

Resource Policies

Resource Collections

Conditional Permissions

Agent Governance

Scope Overrides

API Reference

​Overview

​Step 1: Set Up Your Hierarchy

​Step 2: Create Your Organization Structure

​Step 3: Define Roles and Permissions

​Step 4: Add Users and Agents

​Step 5: Add Resources and Policies

​Step 6: Evaluate Permissions

​What You Built

​Next Steps

Resource Policies

Resource Collections

Conditional Permissions

Agent Governance

Scope Overrides

API Reference

Overview

Step 1: Set Up Your Hierarchy

Step 2: Create Your Organization Structure

Step 3: Define Roles and Permissions

Step 4: Add Users and Agents

Step 5: Add Resources and Policies

Step 6: Evaluate Permissions

What You Built

Next Steps