Set up Claude Code with the Claude apps gateway

The Claude apps gateway is a self-hosted service that sits between your developers' Claude Code clients and the model provider. Developers sign in with your corporate identity provider (IdP) instead of holding API keys or cloud credentials. The gateway holds the upstream credential, enforces model access and managed settings by IdP group, and relays usage telemetry to your observability stack—including Amazon CloudWatch.

The gateway is included in the claude binary. The same executable that runs Claude Code runs the gateway when you pass the gateway subcommand with a configuration file.

Key capabilities

The Claude apps gateway provides centralized control across several dimensions.

• Credentials — The upstream API key lives only in your infrastructure. Developers authenticate through SSO with short-lived tokens.

• Access control — IdP groups map to model allowlists and managed settings policies.

• Settings delivery — The gateway delivers managed settings to signed-in clients.

• Telemetry — Routes OTLP metrics (token counts, model, user identity, latency) to your collector. You can fan out to multiple destinations including CloudWatch, Datadog, Splunk, and ClickHouse.

• Upstream routing — Clients speak the Anthropic Messages API. The gateway translates for each upstream with failover. Supported upstreams include Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry, and the Anthropic API.

Prerequisites

Before you deploy the gateway, confirm that the following requirements are met.

Requirement	Details
Claude Code version	v2.1.195 or later
Identity provider	OpenID Connect (OIDC) provider such as Okta, Microsoft Entra ID, Google Workspace, Keycloak, or Dex
Database	PostgreSQL 14 or later
Model upstream	Amazon Bedrock credentials, Claude Platform on AWS, Google Cloud, Microsoft Foundry, or Anthropic API key
TLS	HTTPS certificate or TLS-terminating ingress
Network	Private-network address (RFC 1918, link-local, CGNAT, IPv6 ULA, or loopback)
Runtime	Linux for production (macOS for local development only)

Deploy the gateway

The following procedure summarizes the quickstart steps. For detailed instructions, see the Claude apps gateway documentation.

To deploy the Claude apps gateway

1. Register an OAuth client in your IdP. Set the redirect URI to https://claude-gateway.your-domain/oauth/callback.

2. Provision a PostgreSQL database (any PostgreSQL 14 or later instance). The gateway runs schema migrations at boot.

3. Write a gateway.yaml configuration file. The following example shows a minimal configuration that uses Amazon Bedrock as the upstream.

   listen:
     host: 0.0.0.0
     port: 8080
     public_url: https://claude-gateway.internal.example.com
   
   oidc:
     issuer: https://login.example.com
     client_id: 0oa1example2
     client_secret: ${OIDC_CLIENT_SECRET}
     allowed_email_domains: [example.com]
     userinfo_fallback: true
   
   session:
     jwt_secret: ${GATEWAY_JWT_SECRET}
     ttl_hours: 1
   
   store:
     postgres_url: ${GATEWAY_POSTGRES_URL}
   
   upstreams:
     - provider: bedrock
       region: us-east-1
       auth: {}
   
   auto_include_builtin_models: true

4. Run the gateway. You can use Docker Compose or run the binary directly.

   claude gateway --config gateway.yaml

5. Verify the authentication surface. Fetch the discovery document, request device authorization, and test browser sign-in at your gateway URL.

6. Sign in a developer to confirm end-to-end connectivity.

Connect developers to the gateway

To point developer machines to your gateway, distribute the following managed settings keys through mobile device management (MDM) or your configuration management tool.

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}

After you distribute the settings, each developer completes the following steps.

To sign in through the gateway

1. Run the /login command in Claude Code.

2. Press Enter on the Cloud gateway screen.

3. Complete browser sign-in with your corporate IdP.

After sign-in, Claude Code routes inference through the gateway and the gateway exports telemetry to the configured destinations.

Route telemetry to Amazon CloudWatch

The gateway supports OTLP/HTTP fan-out to multiple collectors, with identity-stamped exports. Configure telemetry destinations in the gateway.yaml file. Each destination can receive metrics, logs, or traces.

When you configure CloudWatch as a telemetry destination, the gateway stamps each export with the developer's identity from the IdP. Metrics arrive with user, team, and organizational attributes, so the same Coding Agent Insights dashboards populate.

For the complete telemetry configuration options, see the configuration reference.

Availability and limitations

The following table summarizes what the gateway supports and current limitations.

Item	Status
Supported upstreams	Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry, Anthropic API
Supported IdPs	Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex, and other OIDC-compliant providers
Telemetry protocol	OTLP/HTTP with fan-out to multiple destinations
Runtime	Linux for production deployments. macOS is supported for local development only.
Minimum Claude Code version	v2.1.195

Next steps

Use the following resources for detailed deployment instructions, configuration options, and operational guidance.

• Claude apps gateway documentation — Complete setup guide including Docker Compose templates and IdP registration walkthroughs.

• Configuration reference — Full reference for all gateway.yaml options including telemetry destinations, upstream routing, and access policies.

• Deployment guide — Production deployment patterns, scaling, and operational best practices.

After the gateway is sending metrics to CloudWatch, view the dashboards as described in View the dashboards.