HSystem
HSystemHalphas Technology
文件站
控制台

憑證與認證

同一個 API 有四種身分：App 金鑰（你的伺服器）、用戶 access_token（你產品裡的人）、Agent Token（排程／CI）、開發者 session（控制台）。選錯不是「權限不足」而已，而是把金鑰放到不該放的地方。
到控制台拿金鑰錯誤與狀態碼

01對照表

先看這張表，再決定要帶哪一個。

每一支端點頁的「認證」那行，說的就是這裡的其中一種。

憑證送什麼放哪裡代表誰
App 金鑰X-HSystem-Token: id:secret
X-Client-Id + Bearer secret		只有後端你的 App
用戶 access_tokenAuthorization: Bearer …前端或後端 session某一個使用者
Agent TokenX-HSystem-Agent-Token
X-HSystem-Account-Token		CI／伺服器自動化流程
開發者 sessioncookie只在控制台你本人

免憑證的公開端點（Reference 標「免憑證」）不用帶任何 header；需要 client_id 的，直接放在 body 就好。

02逐一說明

每一種憑證能幹嘛、外洩會怎樣。

四張卡都可以直接分享（/credentials#agent）。

01

App 金鑰

你的伺服器代表「這個 App」說話

請求要帶什麼

X-HSystem-Token: {client_id}:{client_secret}

# profile／friends／guest 這一族改用：
X-Client-Id: {client_id}
Authorization: Bearer {client_secret}

放哪裡

只能放後端（Worker／Node／PHP…）或本機 .env。絕對不要打進前端 bundle。

怎麼拿到

開發者控制台 → 選 App → 金鑰。測試 secret 與正式 secret 是兩把，回應與報表會分開。

外洩會怎樣

任何人可以替你寄信、發驗證碼、動商品與金流。立刻到控制台換 key，並查 audit-events。

可以

  • 呼叫 App Secret 類端點：寄信、驗證碼、檔案、商品、收款、webhook
  • 建立收款意圖、退款（退款另外要求 App Secret，不接受只有用戶 token）
  • 以測試 secret（hs_test_…）呼叫，交易會被標成 Test

不行

  • 代表某個終端用戶（讀寫他的 profile、好友、訂單）
  • 取代用戶 token 去呼叫需要「本人」的端點
會撞到的錯誤

401 憑證無效：client_id 與 secret 沒成對，或拿測試 secret 打正式環境

403 pay_service_disabled：服務沒在 App 啟用

02

終端用戶 access_token

代表「你產品裡的那一個人」

請求要帶什麼

Authorization: Bearer {access_token}
X-Client-Id: {client_id}   # 建議一律帶

放哪裡

可放瀏覽器（但要注意 XSS）或收在後端 session。與 App secret 不可混用。

怎麼拿到

POST /v1/auth/login 或 POST /oauth/token → access_token ＋ refresh_token；過期用 POST /v1/auth/refresh 換新的。

外洩會怎樣

只影響那一個使用者。可撤銷 grant 或請使用者改密碼讓 token 失效。

可以

  • 讀寫自己的資料、下單、查自己的訂單
  • 呼叫「本人或 App」的端點（mixed）
  • 半登錄（auth_level=guest）時只拿到更窄的權限

不行

  • 改 App 設定、看別人的資料
  • 在 token 過期後繼續使用（會回 401）
會撞到的錯誤

401 token 過期：先 refresh，換不到就重新登入

403 grant_revoked：使用者已撤銷授權

401／400 X-Client-Id 與 token 所屬 App 不一致

03

Agent Token

給排程、CLI、AI 代理的長期憑證

請求要帶什麼

X-HSystem-Agent-Token: hs_agent_…    # App 級，帶 scopes
X-HSystem-Account-Token: hs_acct_…   # 帳號級，只能碰設定面

放哪裡

CI secret／伺服器環境變數。不要進前端，也不要貼在共用的聊天室。

怎麼拿到

控制台 → App → Agent Token，勾選 scopes 並設到期日。建立時明文只顯示一次。

外洩會怎樣

立刻 rotate（POST /v1/dev/apps/{id}/agent-tokens/{tokenId}/rotate），舊 token 立即失效。

可以

  • App 級：依 scopes 操作（apps／services／pay／orders／users／usage／audit／tokens 共 14 種）
  • 帳號級：GET /v1/dev/bootstrap、GET usage／overview、PATCH App、PUT services
  • 適合「每天自動對帳」「CI 發版後改設定」這類沒有人坐在前面的工作

不行

  • 操作別人的 App（即使是同一個開發者也不行）
  • 帳號級 token 呼叫 App 級端點（一律 403）
  • 建立 App 或改方案（只有開發者 session 可以）
會撞到的錯誤

403 agent_token_scope_missing：回應會列出 required 與 missing

403 agent_token_app_mismatch：token 與路徑上的 App 不同

403 agent_token_route_forbidden：這條路由不開放給 Agent Token

04

開發者 session

你在控制台登入後的那個 session

請求要帶什麼

瀏覽器 cookie（不可攜，沒有可複製的 header）

放哪裡

只在 hsystem.halphastech.com/dev 與 /hq。要從程式自動化，請改用 Agent Token。

怎麼拿到

https://hsystem.halphastech.com/dev/login

外洩會怎樣

等於你的控制台被登入。登出所有裝置並檢查 audit-events。

可以

  • 建立 App、產生金鑰、開通服務、改方案
  • 看用量、稽核、退款等控制台功能

不行

  • 從你的伺服器呼叫（沒有可攜憑證）
  • 在文件站的 Playground 真打（/v1/dev/* 一律只給模擬回應）
會撞到的錯誤

文件站對 dev 類端點只提供模擬，不會真的送出請求

03常見錯法

這四種錯，幾乎每次都一樣。

把 App secret 放進前端打開 DevTools 就有人在賺你的 HCoin／寄垃圾信secret 只放後端；前端只需要用戶的 access_token。
只帶 App secret 去打「本人」端點400 pay_user_required／401 缺少用戶身分這類端點要的是使用者的 access_token，不是 App 金鑰。
user token 過期還一直重試連續 401，log 看不出原因看到 401 先 refresh；refresh 也 401 就重新登入。
用 A App 的 token 打 B App 的路徑401／403 agent_token_app_mismatchclient_id、token、路徑上的 appId 必須是同一個 App。

04標籤對照

端點頁上的「認證」對應到這裡。

看到這幾個字，就知道該帶哪一種憑證。

端點頁顯示意思帶什麼
免憑證公開端點，不用帶任何 header。不用帶
App 金鑰用 client_id 與 secret 代表你的 App。看第 01 節
用戶 token代表某一個終端使用者。看第 02 節
本人或 App用戶 access_token 或 App 金鑰都可以。看第 01 節
開發者 session控制台 cookie，不可攜，只給 /v1/dev/*。看第 04 節

還沒拿到任何金鑰？先到 開發者控制台 建立 App；不想先申請也能在 Playground 用模擬模式把流程跑一次。