>_

# Claude Code AWS Gateway

Authenticate to continue

or
Username Password

## Connect Claude Code

## Dashboard

to
Configure pricing →
Total Cost
-
Cache Savings
-
Requests
-
Avg Latency
-

### Cost Trend

### Cost by Model

Model | Requests | Cost | Avg Latency
--- | --- | --- | ---

### Tool Usage

Tool | Type | Calls
--- | --- | ---

## Virtual Keys

Save this key — it won't be shown again

To set up Claude Code with this key, go to Connect.

Key Prefix | Name | Team | User | Status | Created |
--- | --- | --- | --- | --- | --- | ---

#### No virtual keys yet

Create a virtual key to get started.

## Analytics

Range
7 days
1 day
7 days
14 days
30 days
90 days
Custom range
–
Granularity
Auto
Team
All Teams ×
User
All Users ×
Model
All Models ×
Endpoint
All Endpoints ×
Total Requests ⓘ
-
Active Users ⓘ
-
Total Spend ⓘ
-
Avg Latency ⓘ
-
Cache Hit Rate ⓘ
-
Tool Calls ⓘ
-
Spend Over Time (by Team)
Spend by Team
Spend by Model
Spend by User

User | Team | Requests | Tokens | Spend | Avg $/req
--- | --- | --- | --- | --- | ---

Budget Status
Cost Forecast
Active Users Over Time
Hourly Heatmap (Requests)
Model Mix (by Requests)
Latency Percentiles by Model
Cache Hit Rate Over Time
Token Breakdown by Model
Endpoint Utilization

Endpoint | Requests | Errors | Err % | Avg Lat | p99 Lat
--- | --- | --- | --- | --- | ---

MCP Servers

Server | Tools | Calls | Users | Err Rate
--- | --- | --- | --- | ---

Top MCP Tools (by Calls)
Top Built-in Tools

## Teams

### Default User Budget

Applied to every user who is not assigned to a team.
Loading...

Team | Members | Keys | Team Budget | Resets | Spend | Usage |
--- | --- | --- | --- | --- | --- | --- | ---

#### No teams yet

Create teams to organize members and control spend budgets.

### Spend Overview

### Recent Budget Events

Time | Type | User / Team | Threshold | Spend | Limit | Delivered
--- | --- | --- | --- | --- | --- | ---

## Members

User | Status | Team | Budget | Role | Created |
--- | --- | --- | --- | --- | --- | ---

#### No members yet

Add members to manage who can access the gateway.

## Endpoints

###
How Endpoints Work

Each endpoint is a Bedrock runtime client with its own account, region, and credentials. CCAG selects an endpoint per-request based on the team's routing strategy, endpoint priority, and health status. Adding multiple endpoints lets you pool quota across accounts or regions.

Application Inference Profiles (AIPs)

- AIPs are configured per-model on each endpoint. Use the AIP Overrides panel after creating an endpoint to map specific models to tagged AIP ARNs; models without an override use the system CRI for the endpoint's region scope.

Credentials

- Gateway's own account — Uses the gateway's IAM role or access keys. Works for same-account Bedrock and for cross-account access where the target account grants access via a resource policy on the inference profile.
- Assume an IAM role — Gateway calls STS AssumeRole before each Bedrock call. Use this when the Bedrock quota lives in a different account. Add an External ID to prevent confused-deputy attacks if the role trust policy includes it.

Required IAM permissions

- `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` — required for inference
- `bedrock:ListInferenceProfiles` — required for model discovery and health checks
- `servicequotas:ListServiceQuotas` — optional; needed for quota visibility in this portal

Prompt caching & routing strategy

Bedrock caches the model's internal state (KV cache) for repeated prompt prefixes. Cache hits cost 0.1× the standard input price (90% savings), while cache writes cost 1.25× (25% premium). The cache has a 5-minute sliding TTL — each hit resets the timer. An extended 1-hour TTL is available for Claude 4.5+ models.

- Per-account, per-model — cache is not shared across AWS accounts or models. Each endpoint's account has its own cache.
- Cross-region inference — caching works with CRIS, but requests landing in different regions may miss the cache.
- Exact prefix match — even a single token change in the prefix invalidates the cache. System prompts, tool definitions, and static context should come first.
- Minimum tokens — 1,024 tokens per checkpoint for Sonnet; 4,096 for Opus and Haiku. Below the minimum, the request succeeds but nothing is cached.

Why Sticky User is the default: Claude Code sessions have large, stable prompt prefixes (system prompt + tools + conversation history). Routing the same user to the same endpoint maximizes cache hits. Round Robin spreads users across endpoints, causing each endpoint to see different prefixes and miss the cache — this can significantly increase costs.

#### No endpoints configured

Add a Bedrock endpoint to start routing requests.

## Web Search

###
How Web Search Works

Amazon Bedrock does not support Anthropic's `web_search` server tool natively. When Claude Code asks to search the web, this gateway intercepts the request, executes the search using your configured provider, and returns results in the format Claude expects.

This is a well-known pattern used by API gateways like LiteLLM Proxy to enable web search on providers that don't support it natively. The search happens server-side — Claude Code sees the results as if they came from Anthropic's own search infrastructure.

What's different from Anthropic Direct API

- Search queries go to your chosen provider (not Anthropic's infrastructure)
- No intermediate "Searching..." progress — results arrive together after the search completes
- Citations referencing `encrypted_content` won't work (CC still shows titles + URLs)
- The `web_search` tool is transparently replaced with a regular tool definition for Bedrock

Privacy note: Search queries may contain context from your conversation. If you're working with sensitive code or proprietary information, consider which search provider you trust with those queries.

Active: Loading...

## Notifications

###
How Notifications Work

Configure a single notification destination for all gateway events (budget alerts, rate limits). Events are delivered asynchronously every 30 seconds. Three destination types are supported:

- Webhook — HTTPS endpoint receives JSON POST with event payload
- SNS Topic — Your own AWS SNS topic. Add a resource-based policy granting the gateway task role `sns:Publish`
- EventBridge — Your own custom event bus. Add a resource-based policy granting `events:PutEvents`

BYO resources: Create your own SNS topic or EventBridge bus, then add a resource-based policy allowing the CCAG task role to publish. The Task Role ARN is available as a CDK output (`TaskRoleArn`).

Workflow: Configure a destination → Save as draft → Test delivery → Activate. You can change or deactivate the destination at any time without a redeploy.

Active: Loading...

### Destination

Webhook
HTTPS endpoint receives JSON POST
SNS Topic
Your own AWS SNS topic ARN
EventBridge
Your own custom event bus ARN
URL
IAM Resource Policy Template

Add this statement to the resource's access policy. Replace `<task-role-arn>` with the `TaskRoleArn` CDK output.

### Event Categories

Budget events (warnings, shaping, blocks) Rate limit events (key exceeded RPM)
Event Payload Reference

    {
      "source": "ccag",
      "version": "1",
      "category": "budget",
      "event_type": "budget_warning",
      "severity": "warning",
      "user_identity": "jane@corp.com",
      "team_id": "uuid",
      "team_name": "frontend",
      "detail": {
        "threshold_percent": 80,
        "spend_usd": 41.20,
        "limit_usd": 50.00,
        "percent": 82.4,
        "period": "weekly",
        "period_start": "2026-03-17T00:00:00Z"
      },
      "timestamp": "2026-03-19T14:30:00Z"
    }

Event types by category:
budget: budget_warning, budget_shaped, budget_blocked, team_budget_warning, team_budget_shaped, team_budget_blocked
rate_limit: rate_limit_hit

### Recent Deliveries

Time | Event | Status | Duration | Error
--- | --- | --- | --- | ---

No delivery history yet

## Settings

Authentication
Status

### Authentication Methods

Method | Status | Description |
--- | --- | --- | ---
Virtual Keys |  | Database-backed virtual keys with rate limiting |
OIDC / SSO |  | JWT tokens from identity providers |
Admin Login |  | Username/password bootstrap login |

###
How SSO & SCIM Provisioning Work

CCAG supports two complementary mechanisms for managing user access from your identity provider (Okta, Entra ID, authentik, etc.):

OIDC Single Sign-On (Authentication)

Users authenticate via your IdP using standard OpenID Connect. CCAG validates JWT tokens against the IdP's JWKS endpoint. Supports device code, authorization code, and implicit flows. Multiple IdPs can be active simultaneously.

- By default, any valid OIDC token auto-provisions the user as a member
- Enable SCIM on an IdP to require pre-provisioning (auto-provisioning is disabled for that IdP)

SCIM 2.0 Provisioning (User Lifecycle)

Your IdP pushes user creates, updates, and deactivations to CCAG's SCIM endpoint (`/scim/v2`). This gives you centralized control over who has access — deactivating a user in your IdP immediately blocks their CCAG access.

- SCIM groups control roles (admin/member), not team assignment. Teams are managed separately in CCAG.
- Configure which SCIM group names map to admin role via the "Admin Groups" setting per IdP
- Deactivated users' virtual keys are automatically blocked on the next cache cycle (~5s)

Setup Steps

1. Add your IdP here with its OIDC issuer URL and client ID
2. Enable SCIM on the IdP and generate a bearer token
3. In your IdP, configure a SCIM application pointing to `<your-gateway-url>/scim/v2` with the bearer token
4. Assign users/groups in your IdP — they will be provisioned to CCAG automatically
5. Optionally set admin groups to control which SCIM groups grant admin role

CLI alternative: All SCIM configuration can be automated via `ccag scim enable`, `ccag scim create-token`, and `ccag scim set-admin-groups`.

### Identity Providers

Name | Issuer | Status | SCIM |
--- | --- | --- | --- | ---

#### No identity providers

Add an OIDC provider to enable SSO authentication.

### Session Settings

Session Token TTL | hours How long gateway session tokens remain valid (1–8760 hours). Changing this only affects new tokens.

### Web Search

Mode |
Global Provider | Provider API Key Key is not stored in plain text — re-enter to set globally. Max Results

### Proxy Status

Version |
Proxy URL |
Health | Healthy
Database | Connected
Authentication |
Identity Providers |

## Pricing

Model Prefix | Input $/MTok | Output $/MTok | Cache Read $/MTok | Cache Write $/MTok | Source | Updated |
--- | --- | --- | --- | --- | --- | --- | ---

#### No pricing data

Click "Refresh from AWS" to pull the latest prices, or add entries manually.

### Create Virtual Key

Key Name
A descriptive name to identify this key
Team
Assign to a team for budget enforcement
User
Assign to a specific member

### Edit Key Assignment

Team
User

### Add Member

Username or Email
Team
Optionally assign to a team on creation
Role

### Add Identity Provider

Provider Name
Issuer URL
OIDC issuer URL. JWKS will be auto-discovered.
Client ID (optional)
Audience (optional)
If empty, audience is not validated.
Flow Type
Default Role
Auto-provision users on first login
JWKS URL (optional)
User Identifier Claim
OIDC Scopes Space-separated. Use "openid email profile" for Entra/Okta if email claim is needed.

#### SCIM Provisioning

Enable SCIM provisioning
When enabled, users must be provisioned via SCIM before they can log in. Auto-provisioning is disabled.
Base URL
``
Paste this URL into your identity provider's SCIM configuration.
Admin Groups
Comma-separated. Users in these SCIM groups get admin role. Others get the default role.
Bearer Tokens
Save the provider first, then edit it to generate SCIM tokens and configure admin groups.

### Create Team

Team Name

### Edit Budget

Spend Limit (USD)
Leave empty to remove the limit
Period
Enforcement Policy
Custom Rules (up to 5)
Per-Member Limit (USD)
Max spend per member in this team. Members with explicit budgets are exempt.
Notify Recipients

### Team

User | Budget | Spend | Requests |
--- | --- | --- | --- | ---

Routing Strategy
Assigned Endpoints (drag to reorder priority)
No endpoints assigned — all requests from this team route to the Default endpoint.
Spend Limit (USD)
Leave empty to remove the limit
Period
Enforcement Policy
Custom Rules (up to 5)
Per-Member Limit (USD)
Max spend per member in this team. Members with explicit budgets are exempt.
Notify Recipients
New key created — copy it now, it won't be shown again:
``

Prefix | Name | Owner | Status | Created |
--- | --- | --- | --- | --- | ---

### Delete Team

### Edit User Budget

Spend Limit (USD)
Leave empty to inherit from team or default budget.

### Add Endpoint

Name
Deployment Region
Geographic Scope
Requests are routed across regions within this scope by Bedrock's cross-region inference.
Home Region
API connection region — pick one within the scope.
Credentials
Gateway's own account
Uses the gateway's IAM role or access keys. Also works for cross-account access via resource policy on the target profile.
Assume an IAM role
Gateway calls STS AssumeRole before Bedrock calls. Use when Bedrock quota lives in a different account.
Role ARN
The role must trust the gateway's task role and have `bedrock:InvokeModel*`, `bedrock:ListInferenceProfiles`, and optionally `servicequotas:ListServiceQuotas`.
External ID (optional)
Recommended if the role trust policy includes a condition on `sts:ExternalId`. Prevents confused-deputy attacks.
Enabled
When disabled, this endpoint remains configured but will not receive any traffic.

### Edit Pricing

Input Rate ($/MTok)
Output Rate ($/MTok)
Cache Read Rate ($/MTok)
Cache Write Rate ($/MTok)
AWS SKU (optional)
Internal reference — not required for cost tracking.