Subjects

What is a Subject?

A subject is any entity that can be granted permissions in Bedrock. This includes humans, AI agents, services, and system processes. Bedrock’s unified subject model means you manage all of these with the same APIs and concepts.

Subject Properties

Property	Type	Description
`id`	`string`	Unique Bedrock identifier
`subjectType`	`SubjectTypeEnum`	Type of subject: `user`, `agent`, `service`, `api_key`
`externalId`	`string`	Your system’s identifier (e.g., user ID from your auth provider)
`displayName`	`string?`	Human-readable name
`meta`	`Record<string, unknown>?`	Custom metadata

Subject Types

User

Human users authenticated through your identity provider.

curl -X POST 'https://api.example.com/subjects' \
  -d '{
    "subjectType": "user",
    "externalId": "auth0|123456",
    "displayName": "Jane Doe",
    "meta": {
      "email": "jane@example.com",
      "department": "Engineering"
    }
  }'

Agent

AI agents, LLM-powered assistants, or autonomous workflows.

curl -X POST 'https://api.example.com/subjects' \
  -d '{
    "subjectType": "agent",
    "externalId": "coding-assistant-v2",
    "displayName": "Coding Assistant",
    "meta": {
      "model": "claude-3",
      "capabilities": ["code-review", "documentation"],
      "owner": "engineering-team"
    }
  }'

Service

Backend services, APIs, or microservices that need to perform authorized actions.

curl -X POST 'https://api.example.com/subjects' \
  -d '{
    "subjectType": "service",
    "externalId": "billing-service",
    "displayName": "Billing Service",
    "meta": {
      "version": "2.1.0",
      "environment": "production"
    }
  }'

API Key

A machine credential acting as its own principal—used when an API key authenticates directly (see authentication) rather than on behalf of a user.

curl -X POST 'https://api.example.com/subjects' \
  -d '{
    "subjectType": "api_key",
    "externalId": "ci-deploy-key",
    "displayName": "CI Deploy Key"
  }'

For internal jobs, cron tasks, or platform operations, model them as a service subject.

Memberships

A membership connects a subject to a scope. Without a membership, a subject has no access to a scope.

# Add Jane to the Engineering team
curl -X POST 'https://api.example.com/memberships' \
  -d '{
    "subjectId": "subject_jane",
    "scopeId": "scope_engineering"
  }'

Membership Properties

Property	Type	Description
`id`	`string`	Unique membership identifier
`subjectId`	`string`	The subject being added
`scopeId`	`string`	The scope they’re joining

A membership alone doesn’t grant permissions—you must also assign roles to the membership.

Role Assignments

After creating a membership, assign roles to grant permissions:

# Assign the Editor role to Jane's membership
curl -X POST 'https://api.example.com/role-assignments' \
  -d '{
    "roleId": "role_editor",
    "membershipId": "membership_jane_eng"
  }'

Complete Example: Adding a User

# 1. Create the subject
curl -X POST 'https://api.example.com/subjects' \
  -d '{
    "id": "subject_jane",
    "subjectType": "user",
    "externalId": "user-jane-doe",
    "displayName": "Jane Doe"
  }'

# 2. Create membership in a scope
curl -X POST 'https://api.example.com/memberships' \
  -d '{
    "id": "membership_jane_eng",
    "subjectId": "subject_jane",
    "scopeId": "scope_engineering"
  }'

# 3. Assign a role
curl -X POST 'https://api.example.com/role-assignments' \
  -d '{
    "roleId": "role_editor",
    "membershipId": "membership_jane_eng"
  }'

Jane now has Editor permissions in the Engineering scope. (Whether that reaches descendant scopes depends on the scope type’s permissionMode—by default, override, it does not.)

Complete Example: Adding an AI Agent

# 1. Create the agent subject
curl -X POST 'https://api.example.com/subjects' \
  -d '{
    "id": "subject_assistant",
    "subjectType": "agent",
    "externalId": "code-review-agent",
    "displayName": "Code Review Agent",
    "meta": {"model": "claude-3", "purpose": "code-review"}
  }'

# 2. Add to Engineering scope
curl -X POST 'https://api.example.com/memberships' \
  -d '{
    "id": "membership_assistant_eng",
    "subjectId": "subject_assistant",
    "scopeId": "scope_engineering"
  }'

# 3. Assign a restricted role (Viewer, not Editor)
curl -X POST 'https://api.example.com/role-assignments' \
  -d '{
    "roleId": "role_viewer",
    "membershipId": "membership_assistant_eng"
  }'

The agent can now read in Engineering but cannot write.

External IDs

Use externalId to map Bedrock subjects to your existing user/service identifiers:

# Create subject with external ID
curl -X POST 'https://api.example.com/subjects' \
  -d '{
    "subjectType": "user",
    "externalId": "auth0|abc123",
    "displayName": "Jane Doe"
  }'

# Look up by external ID
curl -X GET 'https://api.example.com/subjects/external/auth0|abc123'

This allows you to:

Sync users from your identity provider
Reference subjects by your system’s IDs
Avoid storing Bedrock IDs in your application

Subject Metadata

Store custom data on subjects for use in conditional permissions:

curl -X POST 'https://api.example.com/subjects' \
  -d '{
    "subjectType": "user",
    "externalId": "jane-doe",
    "displayName": "Jane Doe",
    "meta": {
      "department": "Engineering",
      "clearanceLevel": "secret",
      "certifications": ["aws-sa", "k8s-admin"],
      "hireDate": "2023-01-15"
    }
  }'

Metadata can be used in conditions, which attach to the role-permission edge (condition):

{
  "condition": {
    "==": [{"var": "subject.meta.department"}, "Engineering"]
  }
}

Multiple Memberships

A subject can belong to multiple scopes with different roles:

# Jane is an Editor in Engineering
curl -X POST 'https://api.example.com/memberships' \
  -d '{"subjectId": "subject_jane", "scopeId": "scope_engineering"}'

curl -X POST 'https://api.example.com/role-assignments' \
  -d '{"roleId": "role_editor", "membershipId": "membership_jane_eng"}'

# Jane is a Viewer in Sales (cross-functional visibility)
curl -X POST 'https://api.example.com/memberships' \
  -d '{"subjectId": "subject_jane", "scopeId": "scope_sales"}'

curl -X POST 'https://api.example.com/role-assignments' \
  -d '{"roleId": "role_viewer", "membershipId": "membership_jane_sales"}'

API Reference

Create Subject

Create a new subject

Create Membership

Add a subject to a scope

Create Role Assignment

Assign a role to a membership

Get by External ID

Look up subjects by external ID

Next Steps

Roles

Learn how roles bundle permissions together

Getting Started

Core Concepts

Resources

Tags

Delegation

Use Cases

Modeling Guides

What is a Subject?

Subject Properties

Subject Types

User

Agent

Service

API Key

Memberships

Membership Properties

Role Assignments

Complete Example: Adding a User

Complete Example: Adding an AI Agent

External IDs

Subject Metadata

Multiple Memberships

API Reference

Create Subject

Create Membership

Create Role Assignment

Get by External ID

Next Steps

Roles

​What is a Subject?

​Subject Properties

​Subject Types

​User

​Agent

​Service

​API Key

​Memberships

​Membership Properties

​Role Assignments

​Complete Example: Adding a User

​Complete Example: Adding an AI Agent

​External IDs

​Subject Metadata

​Multiple Memberships

​API Reference

Create Subject

Create Membership

Create Role Assignment

Get by External ID

​Next Steps

Roles

What is a Subject?

Subject Properties

Subject Types

User

Agent

Service

API Key

Memberships

Membership Properties

Role Assignments

Complete Example: Adding a User

Complete Example: Adding an AI Agent

External IDs

Subject Metadata

Multiple Memberships

API Reference

Next Steps