Workspaces (Anthropic-compatible)

Amazon Bedrock Workspaces provide application-level isolation for your generative AI workloads using the Anthropic-compatible Messages API on the bedrock-mantle endpoint. Workspaces enable you to segment your AI applications for cost tracking, observability, and access control.

What is a Workspace?

A Workspace is a logical boundary used to isolate workloads such as applications, environments, or experiments within Amazon Bedrock when using the Anthropic Messages API. Workspaces are the same underlying resource as Projects (OpenAI-compatible) — they are managed using the Projects API and provide the same capabilities:

Workspaces allow you to manage multiple generative AI workloads in production without creating separate AWS accounts or organizations, reducing operational complexity while maintaining security and governance.

Each AWS account has a default workspace (project) where all inference requests are associated. You can create additional workspaces using the Projects API and reference them in Messages API requests using the anthropic-workspace header.

When to use Workspaces

You should use Workspaces when you need to:

Workspaces vs. Projects

Workspaces and Projects (OpenAI-compatible) are the same underlying resource — both are managed via the Projects API. The difference is how you reference them in your inference requests, depending on which API you use:

Getting started with Workspaces

This section walks you through creating a workspace, associating it with Messages API requests, and verifying your setup.

Prerequisites

Before you begin, ensure you have:

Step 1: Set up your environment

Configure your environment variables with your Amazon Bedrock credentials:

export BEDROCK_API_KEY="<your-bedrock-key>"
export BEDROCK_REGION="us-east-1"

Step 2: Create a Workspace

Workspaces are created using the Projects API. Create a workspace (project) with a name and tags for cost monitoring:

curl -X POST "https://bedrock-mantle.$BEDROCK_REGION.api.aws/v1/organization/projects" \
  -H "Authorization: Bearer $BEDROCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Chatbot Production",
    "tags": {
      "Application": "CustomerChatbot",
      "Environment": "Production",
      "Team": "NLPEngineering",
      "CostCenter": "41250"
    }
  }'

Response:

{
  "arn": "arn:aws:bedrock-mantle:us-east-1:123456789012:project/proj_abc123def456",
  "created_at": 1772135628,
  "id": "proj_abc123def456",
  "name": "Claude Chatbot Production",
  "object": "organization.project",
  "status": "active",
  "tags": {
    "Application": "CustomerChatbot",
    "Environment": "Production",
    "Team": "NLPEngineering",
    "CostCenter": "41250"
  }
}

Note the id field — this is the value you pass in the anthropic-workspace header.

Step 3: Associate requests with your Workspace

To associate your Messages API requests with a workspace, include the anthropic-workspace header with the project ID:

curl

curl -X POST "https://bedrock-mantle.$BEDROCK_REGION.api.aws/anthropic/v1/messages" \
  -H "x-api-key: $BEDROCK_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-workspace: proj_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-sonnet-4-6-v1",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, how can you help me today?"}
    ]
  }'

Python (Anthropic SDK)

import anthropic

client = anthropic.Anthropic(
    base_url=f"https://bedrock-mantle.{region}.api.aws/anthropic",
    api_key=bedrock_api_key,
)

response = client.messages.create(
    model="anthropic.claude-sonnet-4-6-v1",
    max_tokens=1024,
    extra_headers={"anthropic-workspace": "proj_abc123def456"},
    messages=[
        {"role": "user", "content": "Hello, how can you help me today?"}
    ]
)

print(response.content[0].text)

All inference requests made with the same workspace ID are grouped together, enabling per-workspace cost tracking, access control, and observability.

Step 4: Verify your Workspace setup

List all workspaces (projects) to verify your workspace was created successfully:

curl -X GET "https://bedrock-mantle.$BEDROCK_REGION.api.aws/v1/organization/projects" \
  -H "Authorization: Bearer $BEDROCK_API_KEY"

Managing Workspaces

Since Workspaces are managed via the Projects API, all project management operations apply. See Working with Projects for detailed instructions on:

Best practices

Recommended Workspace structure

One workspace per application: Create separate workspaces for each distinct application or service.

├── Claude-Chatbot-Production
├── Claude-Chatbot-Staging
├── Claude-Chatbot-Development
├── Claude-Summarizer-Production
└── Claude-Summarizer-Development

Workspace lifecycle management