Skip to main content

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

​
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 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "scope_type_org", "name": "Organization", "config": {"permissionMode": "define"}},
    {"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 'Authorization: Bearer YOUR_TOKEN' \
  -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 'Authorization: Bearer YOUR_TOKEN' \
  -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 'Authorization: Bearer YOUR_TOKEN' \
  -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 'Authorization: Bearer YOUR_TOKEN' \
  -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 'Authorization: Bearer YOUR_TOKEN' \
  -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 'Authorization: Bearer YOUR_TOKEN' \
  -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 'Authorization: Bearer YOUR_TOKEN' \
  -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 'Authorization: Bearer YOUR_TOKEN' \
  -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 'Authorization: Bearer YOUR_TOKEN' \
  -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 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    {"id": "rtype_document", "name": "Document", "scopeId": "scope_acme"}
  ]'

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

# Create a tag for confidential documents
curl -X POST 'https://api.example.com/tags' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"id": "tag_confidential", "key": "classification", "value": "confidential", "scopeId": "scope_acme"}'

# Tag the budget document
curl -X POST 'https://api.example.com/tag-assignments' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"tagId": "tag_confidential", "modelType": "resource", "modelId": "resource_budget"}'

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

# Create a policy: deny agents access to confidential documents
curl -X POST 'https://api.example.com/resource-policies' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -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.type"}, "agent"]
    }
  }'

​
Step 6: Evaluate Permissions

Test your authorization setup: 
# Jane can read the roadmap
curl -X POST 'https://api.example.com/evaluate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -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