Authentication

AI Gateway uses different credentials for different kinds of connections:

• AI clients use a Coder API token to authenticate with AI Gateway as a user.
• Standalone Gateway replicas use AI Gateway keys to connect to the Coder control plane.
• AI Gateway uses provider credentials configured by an administrator to authenticate to upstream AI providers.
• In Bring Your Own Key (BYOK) mode, a user also supplies a personal provider credential or subscription token.

These credentials are not interchangeable. A Gateway key does not authenticate an AI client, and a Coder API token does not authenticate a standalone replica.

Authenticate AI clients

AI Gateway authenticates clients with the same Coder API token that a user uses for the rest of the Coder API. No separate AI Gateway login is required for client traffic. For token creation, expiration, and revocation, refer to Sessions and API tokens.

Authenticating with a Coder token avoids distributing centralized provider API keys, such as OpenAI or Anthropic keys, to individual users. AI Gateway handles upstream credentials centrally and forwards each request to the configured provider on the user's behalf.

The exact environment variable or setting name differs between tools. Refer to the list of supported clients and your tool's documentation for details.

Create a Coder API token

You can generate a token from the Coder dashboard or the CLI.

From the dashboard, go to Account settings > Tokens and create a new token. For long-lived tokens, refer to Sessions and API tokens. For headless or service-account use, refer to Headless authentication.

From the CLI, print your current session token with coder login token:

Or create a new long-lived token with a name and lifetime:

Use short lifetimes for automation and CI to limit the blast radius if a token leaks.

Retrieve your session token

If you're logged in with the Coder CLI, retrieve your current session token with coder login token:

AI Gateway Proxy authentication

For tools that don't support a configurable base URL, AI Gateway Proxy intercepts traffic and forwards it to AI Gateway. The Coder token is supplied in the proxy URL:

The client machine also needs to trust the proxy's CA certificate. For full setup, refer to AI Gateway Proxy setup.

Authenticate standalone Gateway replicas

AI Gateway keys are scoped to the Coder deployment. A standalone AI Gateway uses one of these keys to connect to coderd. Only the built-in Owner role can create, list, and delete these keys. Coder custom roles are organization-scoped and cannot grant the site-level ai_gateway_key permissions.

Create a key with a descriptive name:

The command displays the plaintext key once. Save it immediately in your secret manager because Coder cannot retrieve it later. Coder stores only a short prefix of the key for display and a SHA-256 hash for authentication, never the full secret.

Names must be unique, 64 characters or fewer, and use only lowercase letters, numbers, and hyphens. A name cannot start or end with a hyphen or contain consecutive hyphens. Gateway keys do not expire and cannot be scoped or restricted.

Configure the standalone process with either of the following options, but not both:

• CODER_AI_GATEWAY_KEY or --key supplies the key directly.
• CODER_AI_GATEWAY_KEY_FILE or --key-file reads the key from a file.

A user login and CODER_SESSION_TOKEN are not used by coder ai-gateway start. The same Gateway key can authenticate multiple replicas. Separate keys make it easier to rotate or revoke each deployment independently.

List keys and the most recent heartbeat for each:

A replica records a heartbeat when its control connection is established, then refreshes it every 60 seconds while that connection is active. The heartbeat reports control-connection liveness rather than client request volume. Coder stores one timestamp per key, so replicas that share a key cannot be distinguished.

For usage and flags, refer to the generated CLI reference for creating, listing, and deleting Gateway keys.

Rotate a Gateway key

Rotate a key with a rolling restart. Run more than 1 replica behind a load balancer so client traffic continues during the rollout:

1. Create a new Gateway key.
2. Update the Kubernetes Secret, environment variable, or key file used by every replica.
3. Restart or roll out the standalone deployment so every replica uses the new key.
4. Verify readiness and confirm that the new key has a recent heartbeat.
5. Delete the old key.

Delete a key by name or ID:

Add --yes to skip the confirmation prompt in automation.

Deleting a key rejects new connections immediately. An established session closes when its next heartbeat detects the deletion, within 60 seconds. The replica then tries to reconnect, receives HTTP 401, and treats that as fatal: the process exits non-zero rather than retrying. Stop or update every replica before deleting its key for an orderly rotation.

Authenticate to upstream providers

Administrators configure provider credentials in the Coder dashboard or with the AI Providers API. Standalone replicas fetch this provider configuration from coderd, so do not copy centralized provider credentials into each standalone deployment.

For provider setup and credential failover, refer to Provider configuration.

Bring Your Own Key (BYOK)

In addition to centralized key management, AI Gateway supports Bring Your Own Key (BYOK) mode. Users can provide their own LLM API keys or provider subscriptions, such as Claude Pro or Max and ChatGPT Plus or Pro, while AI Gateway continues to provide observability and governance.

In BYOK mode, users need two credentials:

• A Coder API token to authenticate with AI Gateway.
• Their own LLM credential, such as a personal API key or subscription token, which AI Gateway forwards to the upstream provider.

BYOK and centralized modes can be used together. When a user provides their own credential, AI Gateway forwards it directly. When no user credential is present, AI Gateway uses the administrator-configured provider key. This approach offers centralized keys as a default while allowing individual users to bring their own key.

Coder Agents requests routed through AI Gateway are in-process control plane requests, not external client requests that send their own AI Gateway bearer token. Coder Agents use the same global BYOK setting. When BYOK is enabled, users can save personal API keys for any enabled AI provider from the Agents settings page. Refer to Agents credential selection for the Agents-specific behavior.

Visit individual client pages for configuration details.

Enable or disable BYOK

BYOK is enabled by default. Administrators can disable it for the embedded Gateway with --ai-gateway-allow-byok=false or CODER_AI_GATEWAY_ALLOW_BYOK=false:

For a standalone Gateway, set the option on each replica:

Each replica enforces its own local value, which governs only the traffic that replica handles. The standalone process does not receive the coderd value, so set the option on every replica that should reject BYOK requests. When disabled, BYOK requests are rejected with a 403 Forbidden response, and only centralized provider credentials are permitted.