摘要

OAuth 應用程式可讓外部應用程式代表使用者安全地連接到 Astra。使用者無需共用憑證，而是登入 Astra 並明確授予應用程式權限。本指南說明 OAuth 應用程式的運作方式、如何建立與管理它們，以及何時使用 OAuth 應用程式而非 API 金鑰。

說明

什麼是 OAuth 應用程式？

OAuth 應用程式是您在 Astra 中註冊的應用程式，可讓使用者安全地授權存取其工作區。

當您建立 OAuth 應用程式時，Astra 會產生：

用戶端 ID，用於識別您的應用程式。
用戶端密碼，用於驗證您的應用程式。

當使用者將您的應用程式連接到 Astra 時，他們會被重新導向至 Astra 以登入並檢閱您的應用程式所要求的權限。只有在使用者核准要求後，才會授予存取權。

建議的使用案例

OAuth 應用程式最適合：

連接到客戶 Astra 帳戶的 SaaS 產品
需要在存取 Astra 資料前取得使用者同意的應用程式
為多個客戶或工作區提供服務的多租用戶應用程式
允許使用者透過「連接 Astra」按鈕連接其 Astra 帳戶的整合

何時不使用 OAuth 應用程式

OAuth 應用程式可能不是以下情況的最佳選擇：

內部指令碼和後端自動化
沒有使用者互動的系統對系統整合
在單一組織帳戶下執行的排程作業

對於這些情況，API 金鑰通常較易於管理。

如何建立 OAuth 應用程式

若要建立 OAuth 應用程式：

登入您的 Astra 帳戶。
前往「帳戶」>「OAuth 應用程式」。
按一下「建立應用程式」。

輸入必要的詳細資訊：
- 應用程式名稱 – 授權過程中向使用者顯示的名稱。
- 重新導向 URI – 使用者核准存取後被傳送到的 URL。
- 範圍 – 您的應用程式所需的權限。
按一下「建立」。

重要：請立即儲存您的用戶端密碼

應用程式建立後，Astra 只會顯示一次用戶端密碼。

在離開頁面之前，請複製並將用戶端 ID 和用戶端密碼儲存在安全的位置。

之後，Astra 將繼續顯示用戶端 ID，但無法再次查看完整的用戶端密碼。

了解重新導向 URI

重新導向 URI 是 Astra 在使用者核准或拒絕您的應用程式存取權之後，將使用者傳送到的目的地。

授權期間提供的重新導向 URI 必須與已為 OAuth 應用程式註冊的其中一個重新導向 URI 完全相符。如果值不符，授權要求將會失敗。

範例重新導向 URI

正式環境：

https://your-app.com/oauth/callback

本機開發環境：

http://localhost:8787/callback

了解範圍

範圍定義了您的應用程式可以向 Astra 要求的權限。

使用者可以在決定是否授權您的應用程式之前檢閱這些權限。

可用範圍

範圍	說明
全部	完全存取所有可用的公開 API 功能
聊天	與代理人聊天
代理人：讀取	檢視代理人
代理人：寫入	建立、更新和管理代理人
聯絡人：讀取	檢視聯絡人
聯絡人：寫入	建立、更新和管理聯絡人
對話：讀取	檢視對話記錄
知識：讀取	檢視知識庫
知識：寫入	建立、更新和管理知識庫
Webhooks：管理	建立和管理 Webhooks
分析：讀取	存取分析資料

使用 OAuth 應用程式的最佳實踐

僅要求您需要的權限

僅要求您的應用程式功能所需的範圍。

要求較少的權限有助於使用者了解您的應用程式可以存取哪些內容，並在授權過程中提高信任度。

授權流程如何運作 (使用者體驗)

當使用者將您的 OAuth 應用程式連接到 Astra 時：

使用者在其應用程式中按一下「連接 Astra」。
使用者被重新導向 Astra 的授權頁面。
Astra 會顯示應用程式名稱和要求的權限。
如果使用者尚未登入 Astra，則會提示他們登入。
使用者按一下「授權」或「拒絕」。
如果核准，Astra 會將使用者重新導向至已設定的重新導向 URI。
您的應用程式會收到授權憑證，並可以代表使用者存取 Astra。

這對使用者的意義

使用者永遠不需要與您的應用程式共用其 Astra 密碼。
每位使用者個別授予存取權。
存取權僅適用於使用者已授權的工作區。
使用者可以隨時透過中斷連接應用程式來移除存取權。

管理 OAuth 應用程式

「OAuth 應用程式」頁面會顯示所有已註冊的應用程式。

您可以檢閱現有的應用程式並移除不再需要的應用程式。

如何刪除 OAuth 應用程式

若要刪除 OAuth 應用程式：

登入您的 Astra 帳戶。
開啟「帳戶」→「OAuth 應用程式」。
找到您要移除的應用程式。
刪除應用程式。
確認動作。

刪除應用程式後會發生什麼事？

刪除 OAuth 應用程式時：

將無法再啟動新的授權要求。
現有的存取權杖將被撤銷。
已連接的使用者將立即失去存取權。
如果建立了取代的應用程式，使用者必須重新連接。

OAuth 應用程式與 API 金鑰

應選擇哪種選項？

請使用下表來決定適合您使用案例的驗證方法。

	OAuth 應用程式	API 金鑰
目標使用者	客戶和終端使用者	內部系統和後端服務
需要使用者授權	是	否
使用者同意畫面	是	否
支援多個客戶	是	否
憑證類型	短期存取權杖，可進行重新整理	長期 API 金鑰
典型使用案例	「連接您的 Astra 帳戶」整合	自動化資料同步或內部工作流程