mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: Split AI Gateway Auth docs to its own page (#25496)
The Authentication and BYOK docs are now part of their own section above the Clients subsection. The original PR, coder/coder#25459, was based on a ticket I generated to calculate the drift, but the contents of the Linear ticket were geared more toward documenting _everything_ in the code, which had too much scope and was confusing. Fixes DOCS-148 <!-- If you have used AI to produce some or all of this PR, please ensure you have read our [AI Contribution guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) before submitting. -->
This commit is contained in:
Nick Vigilante
@@ -0,0 +1,117 @@
|
||||
# Authentication
|
||||
|
||||
> [!NOTE]
|
||||
> AI Gateway requires the [AI Governance Add-On](../ai-governance.md).
|
||||
|
||||
AI Gateway authenticates clients with the same Coder API token
|
||||
that a user already uses against the rest of the Coder API.
|
||||
No separate AI Gateway login or credential is required.
|
||||
|
||||
Authenticating with a Coder token avoids distributing provider-specific 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.
|
||||
|
||||
> [!NOTE]
|
||||
> Only Coder-issued tokens can authenticate users to AI Gateway.
|
||||
> AI Gateway will use provider-specific API keys to
|
||||
> [authenticate against upstream AI services](./setup.md#configure-providers).
|
||||
|
||||
The exact environment variable or setting naming may differ from tool to tool.
|
||||
Refer to the list of [supported clients](./clients/index.md),
|
||||
and consult 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](../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself).
|
||||
For headless or service-account use, refer to [Headless authentication](../../admin/users/headless-auth.md).
|
||||
|
||||
From the CLI, print your current session token with [`coder login token`](../../reference/cli/login_token.md):
|
||||
|
||||
```sh
|
||||
coder login token
|
||||
```
|
||||
|
||||
Or create a new long-lived token with a name and lifetime:
|
||||
|
||||
```sh
|
||||
coder tokens create --lifetime 30d -n my-ai-token
|
||||
```
|
||||
|
||||
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, you can retrieve your current session token
|
||||
by using [`coder login token`](../../reference/cli/login_token.md):
|
||||
|
||||
```sh
|
||||
export ANTHROPIC_API_KEY=$(coder login token)
|
||||
export ANTHROPIC_BASE_URL="https://coder.example.com/api/v2/aibridge/anthropic"
|
||||
```
|
||||
|
||||
Alternatively, you can [generate a long-lived API token](../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself)
|
||||
from the Coder dashboard.
|
||||
|
||||
For headless or service-account use, refer to [Headless authentication](../../admin/users/headless-auth.md).
|
||||
|
||||
## AI Gateway Proxy authentication
|
||||
|
||||
For tools that don't support a configurable base URL,
|
||||
[AI Gateway Proxy](./ai-gateway-proxy/index.md) intercepts traffic and forwards it to AI Gateway.
|
||||
The Coder token is supplied in the proxy URL:
|
||||
|
||||
```sh
|
||||
export HTTPS_PROXY="https://coder:$(coder login token)@<proxy-host>:8888"
|
||||
```
|
||||
|
||||
The client machine also needs to trust the proxy's CA certificate.
|
||||
For full setup, refer to [AI Gateway Proxy setup](./ai-gateway-proxy/setup.md).
|
||||
|
||||
## 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 use provider subscriptions
|
||||
(such as Claude Pro/Max or ChatGPT Plus/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** (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 falls back to the admin-configured provider key.
|
||||
This approach offers centralized keys as a default,
|
||||
while allowing individual users to bring their own key.
|
||||
|
||||
Visit individual [client pages](./clients/index.md) for configuration details.
|
||||
|
||||
### Enable or disable BYOK
|
||||
|
||||
BYOK is enabled by default.
|
||||
Administrators can disable it using `--aibridge-allow-byok=false` or `CODER_AIBRIDGE_ALLOW_BYOK=false`:
|
||||
|
||||
```sh
|
||||
coder server --aibridge-allow-byok=false
|
||||
```
|
||||
|
||||
When disabled, BYOK requests are rejected with a `403 Forbidden` response and only centralized key authentication is permitted.
|
||||
|
||||
## Rotate or revoke a token
|
||||
|
||||
To rotate a token without downtime:
|
||||
|
||||
1. Create a new token with `coder tokens create`.
|
||||
2. Update the client's configuration to use the new token.
|
||||
3. Delete the old token from the dashboard or with `coder tokens rm <name>`.
|
||||
|
||||
Deleting a token immediately revokes access.
|
||||
Deleting the user that owns a token revokes every token that user holds at the same time.
|
||||
@@ -13,9 +13,8 @@ There are two ways to connect AI tools to AI Gateway:
|
||||
- AI Gateway Proxy: For tools that don't support base URL configuration, [AI Gateway Proxy](../ai-gateway-proxy/index.md) can intercept traffic and forward it to AI Gateway.
|
||||
|
||||
> [!NOTE]
|
||||
> AI Gateway works with tools running inside or outside
|
||||
> of Coder workspaces. For non-workspace setup, see
|
||||
> [External and Desktop Clients](#external-and-desktop-clients).
|
||||
> AI Gateway works with tools running inside or outside of Coder workspaces.
|
||||
> For non-workspace setup, visit [External and Desktop Clients](#external-and-desktop-clients).
|
||||
|
||||
## Base URLs
|
||||
|
||||
@@ -30,61 +29,7 @@ Replace `coder.example.com` with your actual Coder deployment URL.
|
||||
|
||||
## Authentication
|
||||
|
||||
Instead of distributing provider-specific API keys (OpenAI/Anthropic keys) to users, they authenticate to AI Gateway using their **Coder API token**:
|
||||
|
||||
- **OpenAI clients**: Users set `OPENAI_API_KEY` to their Coder API token
|
||||
- **Anthropic clients**: Users set `ANTHROPIC_API_KEY` to their Coder API token
|
||||
|
||||
> [!NOTE]
|
||||
> Only Coder-issued tokens can authenticate users against AI Gateway.
|
||||
> AI Gateway will use provider-specific API keys to [authenticate against upstream AI services](../setup.md#configure-providers).
|
||||
|
||||
Again, the exact environment variable or setting naming may differ from tool to tool. See a list of [supported clients](#all-supported-clients) below and consult your tool's documentation for details.
|
||||
|
||||
### Retrieving your session token
|
||||
|
||||
If you're logged in with the Coder CLI, you can retrieve your current session
|
||||
token using [`coder login token`](../../../reference/cli/login_token.md):
|
||||
|
||||
```sh
|
||||
export ANTHROPIC_API_KEY=$(coder login token)
|
||||
export ANTHROPIC_BASE_URL="https://coder.example.com/api/v2/aibridge/anthropic"
|
||||
```
|
||||
|
||||
Alternatively, [generate a long-lived API token](../../../admin/users/sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-yourself) via the Coder dashboard.
|
||||
|
||||
## 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 use
|
||||
provider subscriptions (such as Claude Pro/Max or ChatGPT Plus/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** (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 falls back to the admin-configured
|
||||
provider key. This lets organizations offer centralized keys as a default
|
||||
while allowing individual users to bring their own.
|
||||
|
||||
See individual client pages for configuration details.
|
||||
|
||||
### Enabling or disabling BYOK
|
||||
|
||||
BYOK is enabled by default. Administrators can disable it using `--aibridge-allow-byok=false` or `CODER_AIBRIDGE_ALLOW_BYOK=false`:
|
||||
|
||||
```sh
|
||||
coder server --aibridge-allow-byok=false
|
||||
```
|
||||
|
||||
When disabled, BYOK requests are rejected with a `403 Forbidden` response and only centralized key authentication is permitted.
|
||||
For information about authenticating with AI Gateway, visit [AI Gateway Authentication](../auth.md).
|
||||
|
||||
## Compatibility
|
||||
|
||||
@@ -180,3 +125,8 @@ For complete setup instructions, see the [supported client examples](#all-suppor
|
||||
## All Supported Clients
|
||||
|
||||
<children></children>
|
||||
|
||||
## Learn more
|
||||
|
||||
- [AI Gateway Authentication and BYOK](../auth.md)
|
||||
- [AI Gateway Reference](../reference.md)
|
||||
|
||||
@@ -1140,6 +1140,11 @@
|
||||
"description": "How to set up and configure AI Gateway",
|
||||
"path": "./ai-coder/ai-gateway/setup.md"
|
||||
},
|
||||
{
|
||||
"title": "Authentication",
|
||||
"description": "Learn how to authenticate against AI Gateway",
|
||||
"path": "./ai-coder/ai-gateway/auth.md"
|
||||
},
|
||||
{
|
||||
"title": "Client Configuration",
|
||||
"description": "How to configure your AI coding tools to use AI Gateway",
|
||||
|
||||
Reference in New Issue
Block a user