chore: document key scopes for OpenAI and Anthropic for aibridge (#20903)

dannykopping · david-fraley · commit 3b80b90fe8e5 · 2025-11-25T15:48:28.000Z
Closes coder/internal#1135 --------- Signed-off-by: Danny Kopping <danny@coder.com>
diff --git a/docs/ai-coder/ai-bridge/index.md b/docs/ai-coder/ai-bridge/index.md
@@ -2,7 +2,7 @@
 
 ![AI bridge diagram](../../images/aibridge/aibridge_diagram.png)
 
-AI Bridge is a smart proxy for AI. It acts as a man-in-the-middle between your users' coding agents / IDEs
+AI Bridge is a smart gateway for AI. It acts as an intermediary between your users' coding agents / IDEs
 and providers like OpenAI and Anthropic. By intercepting all the AI traffic between these clients and
 the upstream APIs, AI Bridge can record user prompts, token usage, and tool invocations.
 
diff --git a/docs/ai-coder/ai-bridge/setup.md b/docs/ai-coder/ai-bridge/setup.md
@@ -33,6 +33,10 @@ Set the following when routing [OpenAI-compatible](https://coder.com/docs/refere
 
 The default base URL (`https://api.openai.com/v1/`) works for the native OpenAI service. Point the base URL at your preferred OpenAI-compatible endpoint (for example, a hosted proxy or LiteLLM deployment) when needed.
 
+If you'd like to create an [OpenAI key](https://platform.openai.com/api-keys) with minimal privileges, this is the minimum required set:
+
+![List Models scope should be set to "Read", Model Capabilities set to "Request"](../../images/aibridge/openai_key_scope.png)
+
 ### Anthropic
 
 Set the following when routing [Anthropic-compatible](https://coder.com/docs/reference/cli/server#--aibridge-anthropic-key) traffic through AI Bridge:
@@ -42,6 +46,8 @@ Set the following when routing [Anthropic-compatible](https://coder.com/docs/ref
 
 The default base URL (`https://api.anthropic.com/`) targets Anthropic's public API. Override it for Anthropic-compatible brokers.
 
+Anthropic does not allow [API keys](https://console.anthropic.com/settings/keys) to have restricted permissions at the time of writing (Nov 2025).
+
 ### Amazon Bedrock
 
 Set the following when routing [Amazon Bedrock](https://coder.com/docs/reference/cli/server#--aibridge-bedrock-region) traffic through AI Bridge:
diff --git a/docs/images/aibridge/openai_key_scope.png b/docs/images/aibridge/openai_key_scope.png
