[Access Control] 如何使用 API 功能 – HENNGE One Help Center

概要

本文件說明針對正在使用 Access Control 的客戶，開始使用 API 功能的步驟。

注意事項

本文章內容係根據 2026 年 4 月時的產品規格所製作，未來可能會有變更，恕不另行通知。
使用本功能需要 Access Control 的管理者權限。
如需瞭解如何存取管理介面，請參考下方文章。
Access Control 管理介面的存取方法
Access Control API 設有速率限制。
詳細資訊請參考關於速率限制。
各端點的詳細資訊請參考 Developer Site。
https://developers.hennge.com/ （外部連結）

步驟

事前確認事項

Access Control API 的端點如下所示。

https://api.auth.hennge.com/{version-name}

{version-name} 請指定欲使用的 API 版本。
例如，若要呼叫 20241126 版本的 API，請使用 https://api.auth.hennge.com/20241126。
可用的 API 版本請參考本頁下方的生命週期。

發行驗證用戶端

請從 Access Control 管理介面進入［系統］－［API 用戶端］。
在［API 用戶端］畫面左上方選擇［HAC API］按鈕。
點選畫面右上方的［＋新增用戶端］。
設定 API 用戶端的範圍與備註，確認並勾選使用條款後，點選［儲存］。
API 用戶端新增完成後，請記錄「用戶端密鑰」。
※ 用戶端密鑰僅於 API 用戶端發行時顯示，關閉對話框後將無法再次顯示。
若未儲存用戶端密鑰即關閉對話框，請刪除該 API 用戶端並重新發行新的 API 用戶端。

取得存取權杖

請使用已建立的 API 用戶端來取得存取權杖。
※ Access Control API 的驗證流程採用 OAuth 2.0 的 Client Credentials Flow。

向權杖端點發送請求 (shell)

curl -L --request POST \
--url 'https://ap.ssso.hdems.com/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'authorization: Basic BASIC_CREDENTIALS' \
--data grant_type=client_credentials

向權杖端點發送請求 (HTTP)

POST /oauth/token HTTP/1.1 
Host: https://ap.ssso.hdems.com 
Content-Type: application/x-www-form-urlencoded 
Authorization: Basic BASIC_CREDENTIALS

grant_type=client_credentials

※ BASIC_CREDENTIALS 的值，請將 API 用戶端的用戶端 ID 與用戶端密鑰以 Base64 編碼取得。

・BASIC_CREDENTIALS 的取得範例

echo -n ${CLIENT_ID}:${CLIENT_SECRET} | base64

向端點發送請求

取得存取權杖後，即可使用 Access Control API 的各端點。
各端點的詳細資訊請參考 Developer Site。
https://developers.hennge.com/ （外部連結）

關於速率限制

Access Control API 設有速率限制。
根據 API 類型及使用方案，會套用不同的速率限制。

API 類型	合約方案
API 類型	HENNGE One IdP / HENNGE One Basic	HENNGE One IdP Pro / HENNGE One Pro
憑證相關 API (發行、撤銷、下載)	－	5 請求記錄 / 10 秒
CSV 下載 API	－	10 請求記錄 / 10 秒
其他 API	10 請求記錄 / 10 分鐘	1000 請求記錄 / 10 秒

若超過速率限制，將回傳 429 錯誤。
此外，回應主體中會顯示速率限制解除的時間。

・回應主體範例

{
"detail": {
"reason": "too many requests",
"reset_time": "2023-01-01T00:00:00.000Z"
}
}

請於 reset_time 所示時間過後再重新嘗試 API 請求。

生命週期

Access Control API 依本文件所述的生命週期進行版本管理。各版本的階段會不定期更新。

・各版本階段一覽

版本名稱	階段	發佈日	最後更新日	EOL
20241126	GA	2025/02/10	2025/02/10	－
20230822	EOL	2023/10/26	2023/10/26	2026/04/20
20230221	EOL	2023/02/21	2023/08/22	2025/08/25

・階段定義

階段	定義
Beta	處於 Beta 階段的版本不保證運作穩定性及文件提供，因此不建議於實際演練環境的應用程式中使用。建議用於功能測試或測試環境。
GA	處於 GA 階段的版本保證運作穩定性及文件提供，是應用程式使用的最佳階段。若發生運作問題，亦保證系統復原支援。
Sunset	處於 Sunset 階段的版本同樣保證運作穩定性及文件提供。但 Sunset 階段的版本預計將停止運作，建議盡快移轉至新版本。
EOL	EOL 版本已停止提供。隨著版本停止提供，運作穩定性及文件提供將陸續終止。使用 EOL 版本可能影響應用程式運作，請儘速移轉至其他版本。

Access Control API 各版本階段的更新，將依下列規則進行。

當各版本發生下列事件時，會更新各版本階段一覽表。
- 版本 Beta 發佈
- 版本 GA 發佈
- 版本 EOL 決定
當版本決定進入 EOL 時，該版本將進入 Sunset 階段。
其他關於版本階段更新的規則如下：
- GA 與 Sunset 階段合計期間，最短保證 12 個月。
- EOL 預定日將於最短 EOL 預定日的 6 個月前公告。