Introduction - Bedrock

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

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.

Core Concepts

Subjects

Users, API keys, services, or agents that can be granted access

Scopes

Hierarchical organizational units (orgs, teams, projects)

Roles

Named collections of permissions assignable to memberships

Permissions

Granular access rights (e.g., read:documents, write:documents)

Resources

Protected objects with types and hierarchies

How It Works

Subjects are added to Scopes via Memberships
Roles are assigned to Memberships via Role Assignments
Permissions are assigned to Roles via Role Permissions
Resources are created within Scopes with Resource Types
Tags can be applied to resources, subjects, and other entities
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

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

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.

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.

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

​Welcome

​ID Format

​Core Concepts

Subjects

Scopes

Roles

Permissions

Resources

Tags

​How It Works

​Batch Operations

​Authentication and Authorization

​Base URL

​API Groups

​Core Authorization

​Tags & Classification

​Management Models (Bedrock Cloud)

Welcome

ID Format

Core Concepts

How It Works

Batch Operations

Authentication and Authorization

Base URL

API Groups

Core Authorization

Tags & Classification

Management Models (Bedrock Cloud)