跳轉到主要內容
API key 是銜接已登入工作空間管理流程與外部整合、AI agent 的主要憑證。 這一頁是 API key narrative docs 的主來源，回答三件事：
  • 這把 key 可以做什麼
  • 管理 API 的行為是什麼
  • agent 應該怎麼用它打 /public/v1

​
快速結論

  • API key 以 workspace 為範圍，不是全域 token。
  • 管理 API key 的端點使用 JWT 驗證，不是用 API key 管自己。
  • Public Agent API 則使用 API key 本身驗證。
  • 明文 key material 只會在建立成功當下回傳一次。
  • 過期 key 不再授權請求，也不計入 active-key quota。
  • 如果 key 的建立者不再是有效 workspace member，該 key 會失效。

​
格式與傳遞方式

格式： 
trsq_live_<keyId>_<secret>
建議 header： 
x-api-key: trsq_live_<keyId>_<secret>
替代方式： 
Authorization: Bearer trsq_live_<keyId>_<secret>

​
Status 模型

Status意義
active尚未 revoke，且尚未過期
expired尚未 revoke，但 expiresAt 已到
revoked已撤銷；即使同時過期，也以 revoked 為準

​
Role 與 Scope 模型

​
可接受的 role

目前建立 API key 時接受：
  • viewer
  • member
Role適用情境能否呼叫寫入型 public endpoint
viewerread-only agent 與查詢型流程不行
member會驗證、建立、定案或排程工作的 agent可以
重要規則：
  • scope 決定這把 key 可碰哪些 API surface
  • role 決定它在 workspace 中的有效權限
  • 即使你要求了 write scopes，viewer key 打寫入端點仍可能被拒絕

​
Scopes

Scope用途常見端點
workspace_read讀取 workspace context 與訂閱資訊GET /public/v1/workspace
system_strategies_read讀取系統策略模板GET /public/v1/system-strategies
strategies_read讀取 workspace strategiesGET /public/v1/strategies
strategies_write驗證與建立策略、複製模板、定案版本POST /public/v1/strategies/validate, POST /public/v1/strategies, POST /public/v1/strategies/:id/versions/finalize
backtests_read讀取 backtests 與結果GET /public/v1/backtests, GET /public/v1/backtests/:id
backtests_write建立 backtest jobPOST /public/v1/backtests

​
Active-key quota

目前 active-key quota 依 subscription tier 決定：
TierActive key 上限
free5
plus20
pro50
這裡的 active key 指的是：
  • revokedAt = null
  • 且 expiresAt 為 null，或仍在未來
因此：
  • expired key 不會阻擋 replacement key
  • revoked key 不算在 quota 裡

​
管理 API Keys 的 API

這組端點給已登入的 workspace owner 或 admin 使用。 驗證方式： 
Authorization: Bearer <supabase_jwt>
Base path： 
/workspaces/:workspaceId/api-keys

​
列出 API keys

GET /workspaces/:workspaceId/api-keys
這個端點會回傳 key metadata，但不會回傳明文 secret。 Response shape： 
{
  "data": [
    {
      "id": "api_key_123",
      "name": "agent-prod",
      "description": "Production key for autonomous research agent",
      "role": "member",
      "scopes": [
        "workspace_read",
        "system_strategies_read",
        "strategies_read",
        "strategies_write",
        "backtests_read",
        "backtests_write"
      ],
      "keyPrefix": "trsq_live_abcd1234",
      "tokenPreview": "trsq_live_abcd1234_...",
      "status": "active",
      "lastUsedAt": "2026-03-19T08:20:00.000Z",
      "expiresAt": "2026-12-31T23:59:59.000Z",
      "revokedAt": null,
      "createdAt": "2026-03-19T08:00:00.000Z",
      "createdBy": {
        "id": "user_123",
        "email": "owner@example.com",
        "name": "Workspace Owner"
      }
    }
  ]
}

​
建立 API key

POST /workspaces/:workspaceId/api-keys
Request body： 
{
  "name": "agent-prod",
  "description": "Production key for autonomous research agent",
  "role": "member",
  "scopes": [
    "workspace_read",
    "system_strategies_read",
    "strategies_read",
    "strategies_write",
    "backtests_read",
    "backtests_write"
  ],
  "expiresAt": "2026-12-31T23:59:59.000Z"
}
驗證規則：
  • name: 必填，1-100 字元
  • description: 選填，最多 500 字元
  • role: 選填，只接受 member 或 viewer
  • scopes: 選填，但如果提供，至少要有一個 scope
  • expiresAt: 選填，但必須是未來時間
預設行為：
  • 預設 role 是 member
  • 預設 scopes 是寫入型 public-agent workflow 的完整集合
Create response： 
{
  "id": "api_key_123",
  "name": "agent-prod",
  "description": "Production key for autonomous research agent",
  "role": "member",
  "scopes": [
    "workspace_read",
    "system_strategies_read",
    "strategies_read",
    "strategies_write",
    "backtests_read",
    "backtests_write"
  ],
  "keyPrefix": "trsq_live_abcd1234",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "createdAt": "2026-03-19T08:00:00.000Z",
  "apiKey": "trsq_live_abcd1234_super_secret_value"
}
重要說明：
  • apiKey 只會在建立成功當下回傳一次
  • 資料庫保存的是 hash，不是明文 secret

​
撤銷 API key

DELETE /workspaces/:workspaceId/api-keys/:apiKeyId
Response shape： 
{
  "success": true,
  "revokedAt": "2026-03-19T09:00:00.000Z"
}
行為特性：
  • revoke 立即生效
  • 對已撤銷的 key 重複呼叫仍是 idempotent，會回傳 success

​
用 API key 呼叫 Public Agent API

Base path： 
/public/v1

​
建議的第一個請求

對開發者與 AI agent，第一個請求都建議是： 
GET /public/v1/workspace
它可以幫你確認：
  • 這把 key 屬於哪個 workspace
  • 有效 role
  • 已授權的 scopes
  • 可能影響行為的 subscription tier 限制
Example： 
curl -s \
  -H "x-api-key: $TRASEQ_API_KEY" \
  http://localhost:8000/public/v1/workspace

​
最小 workflow

​
Read-only agent

適合 viewer key。
  1. GET /public/v1/workspace
  2. GET /public/v1/system-strategies
  3. GET /public/v1/strategies
  4. GET /public/v1/backtests
建議 scopes： 
[
  "workspace_read",
  "system_strategies_read",
  "strategies_read",
  "backtests_read"
]

​
Write-capable agent

適合 member key。
  1. GET /public/v1/workspace
  2. POST /public/v1/strategies/validate
  3. POST /public/v1/strategies
  4. POST /public/v1/strategies/:id/versions/finalize
  5. POST /public/v1/backtests
  6. GET /public/v1/backtests/:id 輪詢結果
建議 scopes： 
[
  "workspace_read",
  "strategies_write",
  "strategies_read",
  "backtests_write",
  "backtests_read"
]

​
常見錯誤

​
401 Unauthorized

常見原因：
  • 缺少 x-api-key
  • Authorization: Bearer ... 格式不合法
  • key 格式錯誤
  • key 已 revoked
  • key 已 expired
  • key creator 不再是 workspace member
常見訊息： 
Missing API key. Provide x-api-key or Authorization: Bearer <api_key>.

Invalid API key

API key has been revoked

API key has expired

API key creator is no longer a workspace member

​
403 Forbidden

常見原因：
  • scope 不足
  • role 不足，例如 viewer key 去打寫入端點
  • 建立 key 時 active-key quota 已滿
quota error 範例： 
API key limit (5) reached. Revoke unused keys or upgrade your plan.

​
404 Not Found

管理 API 常見情境：
  • DELETE /workspaces/:workspaceId/api-keys/:apiKeyId 指到不存在的 key

​
實務建議

對人類操作人員：
  • 把 API key 當密碼管理，放進 secret manager
  • 每個 agent 或 environment 用獨立 key，不要共用
  • read-only workflow 優先使用 viewer 加 read scopes
  • 需要建立策略或跑 backtest 的 agent 請用 member
  • 能加 expiration 就加，不要無限制放著
  • 不再使用的 key 直接 revoke
對 AI agents：
  • 先打 GET /public/v1/workspace 再決定下一步
  • 寫入前先用 POST /public/v1/strategies/validate
  • 不要假設 backtest 會同步完成，要用 polling
  • agent workflow 只依賴 /public/v1，不要直接走私有 /workspaces/... 寫入路徑
  • 解析錯誤時，先看 HTTP status，再看 response message

​
相關文件