Add docs and management API support for multiple Claude keys

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

README.hf-spaces.md

@@ -56,22 +56,8 @@ cp Dockerfile.hf-spaces Dockerfile
 
 ## Environment Variables
 
-The startup script will automatically create a `config.yaml` from environment variables:
-
-```yaml
-host: "0.0.0.0"
-port: 7860
-auth-dir: "/app/auth"
-debug: false
-
-api-keys:
-  - "your-api-key"
-
-kiro-api-key:
-  - refresh-token: "your-kiro-refresh-token"
-    region: "us-east-1"
-    # profile-arn is auto-fetched from token refresh!
-```
+The startup script will automatically create a `config.yaml` from environment variables.
+See `config.example.yaml` for full configuration options.
 
 ## Usage
 
@@ -80,7 +66,6 @@ Once deployed, use the Space URL as your API base URL:
 ```bash
 # OpenAI-compatible endpoint
 curl https://your-username-your-space.hf.space/v1/chat/completions \
-  -H "Authorization: Bearer your-api-key" \
   -H "Content-Type: application/json" \
   -d '{
     "model": "claude-sonnet-4.5",
@@ -99,6 +84,40 @@ curl https://your-username-your-space.hf.space/v1/chat/completions \
 | `claude-opus-4.5` | Claude 4.5 Opus (may require paid tier) |
 | `claude-3.7-sonnet` | Claude 3.7 Sonnet (legacy, hidden but functional) |
 
+## Claude API Configuration with Multiple Keys
+
+This version supports multiple Claude API keys with round-robin load balancing!
+
+### Via Management UI
+
+1. Access the management panel at `https://your-space.hf.space/management.html`
+2. Go to **AI Providers** → **Claude API Configuration**
+3. Click **Add Configuration**
+4. In the **API Keys** section, add multiple keys with optional per-key proxy URLs
+5. Save the configuration
+
+### Via Config File
+
+You can also configure multiple Claude API keys directly in your `config.yaml`:
+
+```yaml
+claude-api-key:
+  - api-key-entries:
+      # List your API keys and optional proxies here
+      # See documentation for full syntax
+    base-url: "https://api.anthropic.com"
+    priority: 10
+    models:
+      - name: claude-3-5-sonnet-20241022
+        alias: claude-sonnet
+```
+
+**Features:**
+- **Round-robin load balancing**: Requests automatically rotate between all API keys
+- **Per-key proxy support**: Each API key can have its own proxy configuration
+- **Backward compatible**: Single `api-key` field still works
+- **Automatic failover**: If one key fails, the system tries the next one
+
 ## Troubleshooting
 
 ### Token Refresh Errors

internal/api/handlers/management/config_lists.go

@@ -400,13 +400,14 @@ func (h *Handler) PutClaudeKeys(c *gin.Context) {
 }
 func (h *Handler) PatchClaudeKey(c *gin.Context) {
 	type claudeKeyPatch struct {
-		APIKey         *string               `json:"api-key"`
-		Prefix         *string               `json:"prefix"`
-		BaseURL        *string               `json:"base-url"`
-		ProxyURL       *string               `json:"proxy-url"`
-		Models         *[]config.ClaudeModel `json:"models"`
-		Headers        *map[string]string    `json:"headers"`
-		ExcludedModels *[]string             `json:"excluded-models"`
+		APIKey         *string                     `json:"api-key"`
+		APIKeyEntries  *[]config.ClaudeAPIKeyEntry `json:"api-key-entries"`
+		Prefix         *string                     `json:"prefix"`
+		BaseURL        *string                     `json:"base-url"`
+		ProxyURL       *string                     `json:"proxy-url"`
+		Models         *[]config.ClaudeModel       `json:"models"`
+		Headers        *map[string]string          `json:"headers"`
+		ExcludedModels *[]string                   `json:"excluded-models"`
 	}
 	var body struct {
 		Index *int            `json:"index"`
@@ -424,10 +425,20 @@ func (h *Handler) PatchClaudeKey(c *gin.Context) {
 	if targetIndex == -1 && body.Match != nil {
 		match := strings.TrimSpace(*body.Match)
 		for i := range h.cfg.ClaudeKey {
+			// Match by single API key or check if match exists in APIKeyEntries
 			if h.cfg.ClaudeKey[i].APIKey == match {
 				targetIndex = i
 				break
 			}
+			for _, entry := range h.cfg.ClaudeKey[i].APIKeyEntries {
+				if entry.APIKey == match {
+					targetIndex = i
+					break
+				}
+			}
+			if targetIndex != -1 {
+				break
+			}
 		}
 	}
 	if targetIndex == -1 {
@@ -439,6 +450,9 @@ func (h *Handler) PatchClaudeKey(c *gin.Context) {
 	if body.Value.APIKey != nil {
 		entry.APIKey = strings.TrimSpace(*body.Value.APIKey)
 	}
+	if body.Value.APIKeyEntries != nil {
+		entry.APIKeyEntries = append([]config.ClaudeAPIKeyEntry(nil), (*body.Value.APIKeyEntries)...)
+	}
 	if body.Value.Prefix != nil {
 		entry.Prefix = strings.TrimSpace(*body.Value.Prefix)
 	}
@@ -467,7 +481,19 @@ func (h *Handler) DeleteClaudeKey(c *gin.Context) {
 	if val := c.Query("api-key"); val != "" {
 		out := make([]config.ClaudeKey, 0, len(h.cfg.ClaudeKey))
 		for _, v := range h.cfg.ClaudeKey {
-			if v.APIKey != val {
+			// Check if single API key matches
+			if v.APIKey == val {
+				continue
+			}
+			// Check if any API key in APIKeyEntries matches
+			foundInEntries := false
+			for _, entry := range v.APIKeyEntries {
+				if entry.APIKey == val {
+					foundInEntries = true
+					break
+				}
+			}
+			if !foundInEntries {
 				out = append(out, v)
 			}
 		}
@@ -1132,6 +1158,22 @@ func normalizeClaudeKey(entry *config.ClaudeKey) {
 	entry.ProxyURL = strings.TrimSpace(entry.ProxyURL)
 	entry.Headers = config.NormalizeHeaders(entry.Headers)
 	entry.ExcludedModels = config.NormalizeExcludedModels(entry.ExcludedModels)
+
+	// Normalize APIKeyEntries
+	if len(entry.APIKeyEntries) > 0 {
+		normalizedEntries := make([]config.ClaudeAPIKeyEntry, 0, len(entry.APIKeyEntries))
+		for i := range entry.APIKeyEntries {
+			apiKeyEntry := entry.APIKeyEntries[i]
+			apiKeyEntry.APIKey = strings.TrimSpace(apiKeyEntry.APIKey)
+			apiKeyEntry.ProxyURL = strings.TrimSpace(apiKeyEntry.ProxyURL)
+			// Skip empty API keys
+			if apiKeyEntry.APIKey != "" {
+				normalizedEntries = append(normalizedEntries, apiKeyEntry)
+			}
+		}
+		entry.APIKeyEntries = normalizedEntries
+	}
+
 	if len(entry.Models) == 0 {
 		return
 	}