> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring Your Own Key (BYOK)

> Use your own AWS Bedrock credentials for unlimited LLM usage

Bring Your Own Key (BYOK) allows Scale and above plan users to use their own AWS Bedrock credentials for LLM operations. This enables unlimited usage without consuming platform credits, provides cost control through your own AWS billing, and supports data residency requirements.

***

## Why BYOK?

Enterprise teams often have requirements that shared LLM infrastructure can't meet:

**Data residency**: Regulated industries (healthcare, financial services, government) may require that LLM inference stays within specific geographic regions (EU, US, APAC). Shared platform infrastructure doesn't guarantee this. With BYOK, you choose the inference profile and region — US-only, EU-only, or APAC-only routing.

**Cost predictability**: At scale, platform credits can become expensive. BYOK routes LLM requests through your own AWS Bedrock account — the cost shows up on your AWS bill, where you already have visibility, budgets, and cost allocation tags.

**Unlimited usage**: Platform credit limits exist to prevent abuse. Enterprise teams running continuous autonomous operations need unlimited LLM access. BYOK removes that ceiling.

**Compliance**: Some compliance frameworks require organizations to control all data processing. Using your own AWS Bedrock credentials gives you full control over where inference happens and who can audit it.

***

## Benefits

* **Unlimited Usage** — No credit restrictions when using your own credentials
* **Cost Control** — Charges appear on your AWS bill, giving you full visibility and control
* **Data Residency** — Route requests through specific AWS regions (US, EU, APAC) for compliance
* **Automatic Model Selection** — System automatically chooses optimal models
* **Configurable Fallback** — Optional fallback to platform credentials if yours fail; **disabled by default for Enterprise tenants** and can be turned off per workspace (see [Fallback behavior](#fallback-behavior) below)

***

## Fallback behavior

CloudThinker can fall back to platform-managed Bedrock credentials when a BYOK call fails (expired session token, throttling, model access lost). This is convenient for development tenants and unacceptable for some regulated deployments — so the behavior is **opt-in per workspace** and disabled by default for Enterprise and BYOC plans.

### When fallback would trigger (if enabled)

A BYOK call falls back to the platform path only when **all three** are true:

1. The error is retryable — credential expiration, throttling, transient 5xx — not a content or policy violation
2. The agent operation has been marked **fallback-eligible** (most read operations; never autonomous write actions in production)
3. The workspace's fallback setting is **Allow** (not the default for Enterprise)

If any condition fails, the agent surfaces the error to the user instead of routing the request through a different path.

### What happens during a fallback

The request is re-sent to the platform-managed Bedrock account in **the same region** as the original BYOK call — never silently routed to a different jurisdiction. If your BYOK is configured for `eu-west-1`, a fallback runs against the platform's `eu-west-1` Bedrock endpoint or fails closed; it does not transparently fall back to `us-east-1`.

Every fallback emits an audit event with:

* The original BYOK error code
* The platform endpoint that served the retry
* The user, workspace, and conversation that triggered it
* The model invoked and the token count

Audit events are surfaced in **Admin Settings → Audit log** and can be exported to your SIEM via [webhooks](/guide/webhooks/overview).

### Disable fallback (regulated workspaces)

Enterprise admins can enforce that **no request ever leaves the BYOK boundary**:

<Steps>
  <Step title="Open the BYOK settings">
    **Admin Settings → BYOK → Fallback policy**
  </Step>

  <Step title="Set the policy to 'Strict'">
    Three policy options:

    | Policy                                           | Behavior on BYOK failure                                                                               | Typical use                              |
    | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
    | **Allow**                                        | Retry on platform credentials in-region                                                                | Dev / sandbox tenants                    |
    | **Warn**                                         | Retry on platform credentials in-region, but require explicit user re-confirmation on the next session | Mid-market with mixed workloads          |
    | **Strict** *(recommended for Enterprise / BYOC)* | Surface the error; never retry on a different credential                                               | Banks, FSI, healthcare, BYOC deployments |
  </Step>

  <Step title="Lock the policy at the org level (optional)">
    Toggle **Enforce across all workspaces** to prevent workspace admins from changing the policy locally. Only org owners with the `byok:admin` permission can flip this toggle.
  </Step>
</Steps>

<Warning>
  **Strict mode trade-off:** when BYOK credentials are misconfigured or temporarily revoked, agent operations fail outright until the credentials are fixed. This is the intended behavior for regulated environments — *no inference leaves your boundary* takes precedence over availability — but plan operationally for credential rotation, expiry, and quota management. Set up [notifications](/guide/notifications) on BYOK health to catch credential issues before they block on-call work.
</Warning>

### What data is sent during inference

Regardless of fallback policy, every BYOK inference call sends to Bedrock:

* The agent's system prompt and tool definitions
* The conversation history relevant to the current turn
* Any retrieved context (topology, memory, runbooks) the agent is reasoning over

It does **not** send:

* Raw cloud credentials (the agent calls your cloud APIs separately under their own scoped credentials)
* Other workspaces' data
* Customer PII if a tokenization layer is configured in front of the model boundary

For BYOC and self-hosted deployments, the tokenization boundary runs inside your trust boundary; for SaaS BYOK, tokenization is configured per workspace in **Admin Settings → Data Protection**.

***

## Prerequisites

* **Scale, Scale +, or Enterprise subscription plan** - BYOK is only available on Scale and above (see [Pricing & Plans](/guide/billing/pricing))
* **AWS account** with Amazon Bedrock access enabled
* **IAM credentials** with Bedrock permissions (access key ID and secret access key)
* **Model access** - Both Claude Sonnet 4.5 and Opus 4.5 models must be enabled in your AWS account

***

## Supported Providers

<Tabs>
  <Tab title="AWS IAM (Current)">
    ### AWS IAM Credentials

    Use your AWS IAM user or role credentials to authenticate with Amazon Bedrock.

    **Required Credentials:**

    * Access Key ID
    * Secret Access Key
    * Session Token (optional, for temporary credentials)

    **Benefits:**

    * Works with existing IAM users and roles
    * Supports temporary credentials via AWS STS
    * Automatic token refresh for session tokens
    * Full integration with AWS security policies

    <Info>
      Long-term credentials (AKIA prefix) enable automatic session token refresh. Temporary credentials (ASIA prefix) cannot be automatically refreshed.
    </Info>
  </Tab>

  <Tab title="Bedrock API Keys (Coming Soon)">
    ### Bedrock API Keys

    Direct API key authentication for Amazon Bedrock will be available in a future release.

    This will provide:

    * Simplified credential management
    * Direct API key authentication
    * No IAM policy configuration required

    <Warning>
      Bedrock API Keys are not yet available. Currently, only AWS IAM credentials are supported.
    </Warning>
  </Tab>
</Tabs>

***

## AWS Bedrock Model Access

Before configuring BYOK, you must request access to Claude models in your AWS account. While AWS has simplified access for many serverless models (granted automatically upon first invocation), Claude models still require manual approval via a use case form. For more information, refer to the [AWS Bedrock Model Access documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html).

### Request Access to Claude Models

<Steps>
  <Step title="Open Amazon Bedrock Console">
    Log in to [AWS Console](https://console.aws.amazon.com/) and navigate to
    [Amazon Bedrock](https://console.aws.amazon.com/bedrock/)
  </Step>

  <Step title="Navigate to Model Access">
    In the left navigation pane, click **Model access**
  </Step>

  <Step title="Modify Model Access">Click **Modify model access** button</Step>

  <Step title="Select Claude Models">
    Enable access to both:

    * **Claude Sonnet 4.5** (`anthropic.claude-sonnet-4-5-20250929-v1:0`)
    * **Claude Opus 4.5** (`anthropic.claude-opus-4-5-20251101-v1:0`)
  </Step>

  <Step title="Submit Use Case Details">
    Click **Submit use case details** and complete the form with:

    * Your use case description
    * Expected usage patterns
    * Compliance requirements (if applicable)
  </Step>

  <Step title="Wait for Approval">
    Access is typically granted immediately upon successful submission. You'll
    receive confirmation when access is enabled.
  </Step>
</Steps>

<Info>
  **Important:** You must request access to **both** Sonnet 4.5 and Opus 4.5
  models. CloudThinker automatically selects the appropriate model based on task
  requirements.
</Info>

***

## IAM Credentials Setup

Your AWS IAM user must have permissions to invoke Bedrock models. Follow these steps to create an IAM user with the required permissions using AWS CLI.

### Step 1: Create IAM User

```bash theme={null}
aws iam create-user --user-name bedrock-byok-user
```

### Step 2: Create Policy File

```bash theme={null}
cat > bedrock-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-sonnet-4-5-20250929-v1:0",
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-opus-4-5-20251101-v1:0",
        "arn:aws:bedrock:*:*:inference-profile/global.anthropic.claude-sonnet-4-5-20250929-v1:0",
        "arn:aws:bedrock:*:*:inference-profile/global.anthropic.claude-opus-4-5-20251101-v1:0",
        "arn:aws:bedrock:*:*:inference-profile/us.anthropic.claude-sonnet-4-5-20250929-v1:0",
        "arn:aws:bedrock:*:*:inference-profile/us.anthropic.claude-opus-4-5-20251101-v1:0",
        "arn:aws:bedrock:*:*:inference-profile/eu.anthropic.claude-sonnet-4-5-20250929-v1:0",
        "arn:aws:bedrock:*:*:inference-profile/eu.anthropic.claude-opus-4-5-20251101-v1:0",
        "arn:aws:bedrock:*:*:inference-profile/apac.anthropic.claude-sonnet-4-5-20250929-v1:0",
        "arn:aws:bedrock:*:*:inference-profile/apac.anthropic.claude-opus-4-5-20251101-v1:0"
      ]
    },
    {
      "Effect": "Allow",
      "Action": ["sts:GetSessionToken"],
      "Resource": "*"
    }
  ]
}
EOF
```

### Step 3: Attach Policy to User

```bash theme={null}
aws iam put-user-policy \
  --user-name bedrock-byok-user \
  --policy-name BedrockInvokePolicy \
  --policy-document file://bedrock-policy.json
```

### Step 4: Create Access Keys

```bash theme={null}
aws iam create-access-key --user-name bedrock-byok-user
```

Save the `AccessKeyId` and `SecretAccessKey` from the output - you'll need these for CloudThinker.

### Step 5: Verify Credentials

Configure a local profile to test the credentials:

```bash theme={null}
aws configure --profile bedrock-byok-user
```

Enter the access key ID and secret access key when prompted. Then verify:

```bash theme={null}
aws sts get-caller-identity --profile bedrock-byok-user
```

<Info>
  These commands require an AWS profile with IAM administrative permissions (`iam:CreateUser`, `iam:PutUserPolicy`, `iam:CreateAccessKey`). Alternatively, you can create the IAM user via the [AWS Console](https://console.aws.amazon.com/iam/).
</Info>

***

## Setup in CloudThinker

Once you have AWS Bedrock model access and IAM credentials configured, set up BYOK in CloudThinker:

<Steps>
  <Step title="Navigate to BYOK Settings">
    Go to **Settings** → **BYOK Settings** (or navigate to `/byok-settings` in
    the app)
  </Step>

  <Step title="Select AWS Bedrock">
    Choose **AWS Bedrock** as your provider
  </Step>

  <Step title="Enter Credentials">
    Provide your AWS credentials:

    * **Access Key ID** - Your AWS access key
      (AKIA or ASIA prefix)
    * **Secret Access Key** - Your AWS secret key
    * **Session Token** (optional) - Required only for temporary credentials
  </Step>

  <Step title="Select Inference Profile">
    Choose an inference profile:

    * **Global** - Routes to any commercial AWS region
    * **US** - Routes within US regions only
    * **EU** - Routes within EU regions only (data residency)
    * **APAC** - Routes within APAC regions only
  </Step>

  <Step title="Test Connection">
    Click **Test Connection** to verify:

    * Credentials are valid
    * Both Sonnet 4.5 and Opus 4.5 models are accessible
    * Permissions are correctly configured
  </Step>

  <Step title="Save Configuration">
    After successful test, click **Save** to store your BYOK configuration
  </Step>
</Steps>

<Warning>
  Credentials are encrypted and stored securely. They are never exposed in API
  responses or logs. Only Scale and above plan users can configure BYOK.
</Warning>

***

## Inference Profiles

Bedrock inference profiles control how requests are routed across AWS regions. Choose the profile that best matches your requirements:

| Profile    | Purpose                                                     |
| ---------- | ----------------------------------------------------------- |
| **Global** | Routes to any commercial AWS region for maximum throughput  |
| **US**     | Routes within US regions only for US data residency         |
| **EU**     | Routes within EU regions only for GDPR compliance           |
| **APAC**   | Routes within APAC regions only for regional data residency |

<Info>
  For supported regions and inference profile details, refer to the [AWS Bedrock Supported Regions and Models documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html).
</Info>

***

## How It Works

### Automatic Model Selection

CloudThinker automatically selects the optimal model based on task requirements. You don't need to manually select models - the system chooses the best option automatically. For more details about the available models, refer to the [AWS Bedrock Supported Foundation Models documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html).

### Workspace Owner Inheritance

When a workspace owner configures BYOK, all workspace members automatically inherit access to those credentials. This means:

* Workspace owner configures BYOK once
* All members can use BYOK without individual configuration
* Credentials are managed centrally by the workspace owner
* Members' LLM usage routes through the owner's AWS account

### Fallback Mechanism

If your BYOK credentials fail (due to rate limits, expired tokens, or permission issues), CloudThinker automatically falls back to platform credentials. This ensures:

* No service interruption
* Seamless user experience
* Automatic recovery when credentials are restored

***

## Troubleshooting

<Accordion title="Model access denied errors">
  * Verify you've submitted the use case form in Bedrock Console
  * Check that both Sonnet 4.5 and Opus 4.5 models are enabled
  * Confirm access was granted (check Model access page in Bedrock Console)
  * Wait a few minutes after form submission for access to propagate
</Accordion>

<Accordion title="IAM permission errors">
  * Verify your IAM policy includes `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream`
  * Check that model ARNs in the policy match the models you're using
  * Ensure inference profile ARNs are included if using profiles (global, us, eu, apac)
  * Test IAM permissions directly in AWS Console
</Accordion>

<Accordion title="Credential validation failures">
  * Verify access key ID and secret access key are correct
  * Check that credentials haven't been rotated or revoked
  * For temporary credentials, ensure session token hasn't expired
  * Test credentials using AWS CLI: `aws sts get-caller-identity`
</Accordion>

<Accordion title="Test connection fails">
  * Verify both Sonnet 4.5 and Opus 4.5 models are accessible
  * Check IAM permissions include both model ARNs
  * Ensure Bedrock service is enabled in your AWS account
  * Check AWS region selection matches your model access
</Accordion>

<Accordion title="BYOK not working in workspace">
  * Verify workspace owner has configured BYOK
  * Check that BYOK is enabled (not disabled) in settings
  * Confirm workspace owner's plan is Scale, Scale +, or Enterprise
  * Check workspace owner's credentials are still valid
</Accordion>

<Accordion title="Session token expiration">
  * Long-term credentials (AKIA) are automatically refreshed
  * Temporary credentials (ASIA) cannot be refreshed - reconfigure with new credentials
  * Check `session_token_expires_at` timestamp in configuration
  * Reconfigure if automatic refresh fails
</Accordion>