安全性 — TokSpan 文件

API 金鑰管理

絕不將 API 金鑰寫死在程式碼中——請使用環境變數或機密管理工具（AWS Secrets Manager、GCP Secret Manager、HashiCorp Vault）
絕不將 API 金鑰提交至 Git——將 .env 加入 .gitignore。使用 git-secrets 或 truffleHog 掃描您的儲存庫歷史
為每個環境使用獨立 API 金鑰——開發／staging／生產金鑰彼此獨立。即使開發金鑰外洩，生產環境也不受影響
為每個 API 金鑰設定範圍——在建立金鑰時限制模型存取、設定消費上限並加入 IP 白名單

金鑰輪換

每 90 天輪換 API 金鑰。以下是附帶驗證步驟的安全輪換程序：

import os
import requests

# Step 1: Create new key via Dashboard or API
NEW_KEY = "sk-new-key-from-dashboard"

# Step 2: Update environment (do this atomically with your deploy)
# In production, use a secrets manager: AWS Secrets Manager, GCP Secret Manager, or Vault
os.environ["TOKSPAN_API_KEY"] = NEW_KEY

# Step 3: Verify new key works
response = requests.post(
    "https://api.tokspan.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {NEW_KEY}"},
    json={"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}]},
    timeout=10,
)
assert response.status_code == 200, f"New key validation failed: {response.status_code}"

# Step 4: Revoke old key in Dashboard → API Keys
# Only do this AFTER confirming new key works in production
print("New key validated. Revoke old key in Dashboard now.")

後端代理（瀏覽器／行動裝置必須使用）

絕不從客戶端程式碼直接呼叫 TokSpan。暴露在瀏覽器或行動應用程式中的 API 金鑰可被任何人擷取。請一律透過您的後端進行路由：

Browser App → Your Backend API → TokSpan API
                      ↑
              API key lives here
          (never reaches the client)

您的後端驗證使用者 Session 後，使用伺服器端 API 金鑰轉發 AI 請求。客戶端永遠不會看到金鑰。

IP 白名單

將每個 API 金鑰限制為特定 IP 位址或 CIDR 範圍。即使金鑰外洩，也無法從未經授權的網路使用。在儀表板 → API 金鑰 → 編輯 → IP 白名單中設定。對於生產金鑰，僅將您後端伺服器的出口 IP 加入白名單。

啟用 MFA

使用多重要素驗證保護您的 TokSpan 儀表板帳號。可透過 TOTP 驗證器應用程式（Google Authenticator、Authy、1Password）使用。在儀表板 → 設定 → 安全性 → MFA 中啟用。

稽核與監控

記錄金鑰使用情況以偵測異常：

python
# Monitor API key usage via response headers
import logging

def audit_request(response, key_name):
    usage = response.json().get("usage", {})
    logging.info(f"[{key_name}] model={response.json()['model']} "
                 f"tokens={usage.get('total_tokens', 0)} "
                 f"remaining_rpm={response.headers.get('x-ratelimit-remaining-requests', '?')}")

在儀表板中，定期檢視每個金鑰的活動記錄。留意：非預期的模型使用、Token 用量激增、來自陌生 IP 的請求或不尋常的時段。

若金鑰遭到外洩

立即撤銷——儀表板 → API 金鑰 → 撤銷（60 秒內生效）
產生新金鑰——並更新您的應用程式
稽核舊金鑰的記錄——在刪除前檢查是否有任何未經授權的使用
調查外洩原因——檢查 Git 歷史、CI 記錄、錯誤訊息、客戶端程式碼
加強範圍限制——為替換金鑰加入 IP 白名單並降低消費上限

遺失的金鑰無法復原。TokSpan 僅在建立時顯示一次您的 API 金鑰。我們僅儲存加密後的雜湊值。若您遺失金鑰，請撤銷並產生新的。