API 金鑰

API 金鑰是使用程式存取 Boring API 的主要驗證方式。本指南說明如何安全地建立、管理與使用 API 金鑰。

什麼是 API 金鑰？

API 金鑰是用來驗證 API 請求的唯一識別碼。每把金鑰皆具備：

• 以 boring_ 作為前綴
• 綁定於你的 Google 帳號（電子郵件）
• 可自訂名稱方便辨識
• 會記錄最後使用時間
• 可隨時停用或刪除

建立 API 金鑰

步驟說明

1. 登入 Boring 控制台
2. 點擊導覽列中的 Settings
3. 在 API Keys 區塊內選擇 「Generate New API Key」
4. 輸入具描述性的名稱：
   • 推薦範例：「Production Server」、「Development」、「Mobile App」、「QA Testing」
   • 不建議：「Key1」、「Test」、「My Key」
5. 點擊 「Generate」
6. 立即複製 API 金鑰——之後將無法再次查看
7. 將金鑰安全保存（環境變數、秘密管理服務等）

金鑰格式

boring_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

• 前綴：boring_
• 總長度：43 個字元
• 內容：大小寫英數混合字串

管理 API 金鑰

檢視金鑰列表

前往 Settings 頁面即可查看所有 API 金鑰：

注意：為安全起見，介面只會顯示金鑰的前幾個字元。

追蹤使用狀況

每把金鑰會顯示：

• Created：建立時間
• Last Used：最近一次成功呼叫 API 的時間（或顯示「Never」）

這有助於你：

• 找出長期未使用的金鑰並刪除
• 監控是否有可疑的使用紀錄

刪除 API 金鑰

刪除金鑰的步驟：

1. 前往 Settings 頁面
2. 找到欲刪除的金鑰
3. 點擊 「Delete」
4. 再次確認刪除

重要：刪除後金鑰立即失效，所有使用該金鑰的服務都會收到驗證失敗的回應。

使用 API 金鑰

請求標頭

在每一個 API 請求中，把金鑰放在 boring-api-key 標頭：

POST /v2/posts HTTP/1.1
Host: boring.aiagent-me.com
Content-Type: application/json
boring-api-key: boring_xxxxxxxxxxxxx

{
  "post": {...}
}

程式碼範例

Python（requests）

import requests
import os

API_KEY = os.environ.get("BORING_API_KEY")
API_URL = "https://boring.aiagent-me.com/v2/posts"

headers = {
    "boring-api-key": API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(API_URL, headers=headers, json=post_data)

JavaScript（Node.js）

const API_KEY = process.env.BORING_API_KEY;
const API_URL = "https://boring.aiagent-me.com/v2/posts";

const response = await fetch(API_URL, {
  method: "POST",
  headers: {
    "boring-api-key": API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(postData)
});

Python（http.client）

import http.client
import json
import os

conn = http.client.HTTPSConnection("boring.aiagent-me.com")

headers = {
    "boring-api-key": os.environ["BORING_API_KEY"],
    "Content-Type": "application/json"
}

conn.request("POST", "/v2/posts", json.dumps(post_data), headers)
response = conn.getresponse()

cURL

export BORING_API_KEY="boring_xxxxxxxxxxxxx"

curl -X POST https://boring.aiagent-me.com/v2/posts \
  -H "boring-api-key: $BORING_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

安全性最佳實務

1. 使用環境變數

切勿把金鑰硬寫在程式碼中！

正確示範：

import os
API_KEY = os.environ.get("BORING_API_KEY")

錯誤示範：

API_KEY = "boring_abc123..."  # 千萬不要這樣做！

2. 將機密檔案加入 .gitignore

若使用 .env 檔案，務必排除在版控之外：

# .gitignore
.env
.env.local
*.env

3. 定期輪替金鑰

建議做法：

• 每 3 至 6 個月輪替正式環境金鑰
• 團隊成員離職後立即重新產生金鑰
• 為不同服務或環境建立獨立金鑰

4. 依環境使用不同金鑰

# Development
BORING_API_KEY=boring_dev_xxxxxxxxxxxxx

# Staging
BORING_API_KEY=boring_staging_xxxxxxxxxxxxx

# Production
BORING_API_KEY=boring_prod_xxxxxxxxxxxxx

並在 Settings 頁面使用對應名稱方便辨識。

5. 監控金鑰使用情況

定期檢查 Settings 中的 Last Used 欄位：

• 找出長期未使用的金鑰並刪除
• 偵測是否存在異常使用
• 了解各服務的實際使用狀況

6. 金鑰外洩時的應對措施

若懷疑金鑰已外洩：

1. 到 Settings 頁面立即刪除該金鑰
2. 重新產生一把新金鑰並設定不同名稱
3. 更新應用程式所使用的金鑰
4. 追查外洩來源與原因

疑難排解

驗證錯誤

當伺服器回傳驗證錯誤時，可能會看到以下內容：

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

請確認：

1. 標頭名稱完全符合 boring-api-key（大小寫敏感）
2. 金鑰具有 boring_ 前綴
3. 金鑰未在 Settings 頁面被刪除
4. 金鑰值中沒有多餘空白或換行

金鑰無法使用

若看似正確的金鑰仍無法使用：

1. 回到 Settings 頁面確認金鑰前幾碼是否一致
2. 確認貼上時沒有遺漏任何字元
3. 避免隱藏字元（建議直接從終端機或編輯器複製）
4. 嘗試重新產生新金鑰並測試

Last Used 沒有更新

「Last Used」欄位會在以下情況更新：

• 成功驗證 API 金鑰
• API 請求完成處理

介面上可能需要數分鐘才會同步顯示最新時間。

API 端點

列出 API 金鑰

GET /api/keys HTTP/1.1
Host: boring.aiagent-me.com
Cookie: session=...

回應：

{
  "keys": [
    {
      "id": "uuid",
      "name": "Production",
      "key_preview": "boring_abc...",
      "created_at": "2025-01-15T10:30:00Z",
      "last_used_at": "2025-01-20T15:45:00Z",
      "is_active": true
    }
  ]
}

注意：此端點需要控制台登入（session cookie），不接受 API 金鑰。

刪除 API 金鑰

DELETE /api/keys/{key_id} HTTP/1.1
Host: boring.aiagent-me.com
Cookie: session=...

注意：此端點同樣需要控制台登入（session cookie），不接受 API 金鑰。

多把 API 金鑰的應用

你可以為不同場景建立多組 API 金鑰：

好處：

• 隔離性：單一金鑰外洩不影響其他服務
• 追蹤性：清楚掌握哪個服務發出的請求
• 快速撤銷：可針對特定整合停用而不影響其他環境

下一步

取得 API 金鑰後，你已準備好開始發佈：

• 發佈 API：了解發佈端點
• 程式範例：查看完整程式碼範例
• 支援平台：閱讀各平台詳細指南