API Key

API Key 是你存取 Vecstruct 所有服務的憑證。每個 API Key 都可以獨立設定權限範圍，讓你根據使用場景給予最小必要的權限。

取得 API Key

登入 Vecstruct Dashboard
前往 Settings → API Keys
點擊 新增 API Key
輸入名稱、選擇權限、選擇綁定的專案
複製 Key（只會顯示一次，請立刻儲存）

API Key 格式為 sk- 開頭，例如：sk-a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6

使用方式

在每個 API 請求的 Header 中帶上 API Key：

Authorization: Bearer sk-your-api-key-here

權限說明

建立 API Key 時可以選擇開放哪些功能。根據你的使用場景，只開放必要的權限是最安全的做法。

權限	說明
`gateway.chat`	呼叫 AI 對話（Chat Completions）
`gateway.embeddings`	呼叫 Embedding 模型
`gateway.rerank`	呼叫 Rerank 模型
`query.search`	直接查詢知識庫（不經過 LLM）
`source.read`	讀取文件清單
`source.write`	上傳、刪除文件
`project.read`	讀取專案設定
`project.write`	修改專案設定
`usage.read`	查看使用量統計
`memory.read`	讀取 Agent Memory
`memory.write`	新增、修改、刪除 Memory
`audit.read`	查詢 Audit Log
`audit.export`	匯出 Audit Log

建議的權限組合

使用場景	建議開放的權限
前端嵌入式聊天元件	`gateway.chat`
前端元件（含 Memory）	`gateway.chat` + `memory.read`
後端 AI 整合（基本）	`gateway.chat` + `gateway.embeddings` + `gateway.rerank` + `query.search` + `usage.read` + `memory.read`
後端完整整合	全部權限

專案綁定

每個 API Key 可以綁定一個或多個專案（Project）。綁定後，用這個 Key 發出的 AI 對話請求，預設會自動注入對應專案的知識庫。

沒有綁定專案的 Key 可以在每個請求裡手動指定 vecstruct.project_id。

安全注意事項

API Key 一旦洩露，任何人都可以用你的配額呼叫 API。

不要把 API Key 寫死在程式碼裡或提交到 Git
使用環境變數管理 Key
前端嵌入式場景只給 gateway.chat 最小權限
不再使用的 Key 立刻撤銷

撤銷 API Key：前往 Dashboard → API Keys → 點擊對應 Key → 撤銷

查詢 API Key 資訊

你可以用 API 查詢目前 Key 的權限和綁定的專案：

curl https://api.vecstruct.com/v1/auth/me \
  -H "Authorization: Bearer $VECSTRUCT_API_KEY"

回應範例：

{
  "success": true,
  "data": {
    "user_id": "...",
    "project_ids": ["proj-123"],
    "permissions": ["gateway.chat", "memory.read", "usage.read"]
  }
}

取得 API Key​

使用方式​

權限說明​

建議的權限組合​

專案綁定​

安全注意事項​

查詢 API Key 資訊​