摘要

OAuth 应用允许外部应用程序代表用户安全地连接到 Astra。用户无需共享凭证，而是登录到 Astra 并明确授予应用程序权限。本指南将解释 OAuth 应用的工作原理、如何创建和管理它们，以及何时使用 OAuth 应用而不是 API 密钥。

说明

什么是 OAuth 应用？

OAuth 应用是您在 Astra 中注册的应用程序，用于允许用户安全地授权访问其工作区。

创建 OAuth 应用时，Astra 会生成：

客户端 ID，用于标识您的应用程序。
客户端密钥，用于验证您的应用程序。

当用户将您的应用程序连接到 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 功能
聊天	与代理聊天
代理：读取	查看代理
代理：写入	创建、更新和管理代理
联系人：读取	查看联系人
联系人：写入	创建、更新和管理联系人
对话：读取	查看对话历史记录
知识：读取	查看知识库
知识：写入	创建、更新和管理知识库
Webhook：管理	创建和管理 Webhook
分析：读取	访问分析数据

处理 OAuth 应用的最佳实践

仅请求您需要的权限

仅请求应用程序功能所需的范围。

请求更少的权限有助于用户了解您的应用程序可以访问的内容，并提高授权过程中的信任度。

授权流程如何工作（用户体验）

当用户将您的 OAuth 应用连接到 Astra 时：

用户在您的应用程序中点击“连接 Astra”。
用户将被重定向到 Astra 的授权页面。
Astra 会显示应用程序名称和请求的权限。
如果用户尚未登录，Astra 会要求用户登录。
用户点击“授权”或“拒绝”。
如果获准，Astra 会将用户重定向到配置的重定向 URI。
您的应用程序会收到授权凭证，并可以代表用户访问 Astra。

这对用户意味着什么

用户永远不需要与您的应用程序共享其 Astra 密码。
每个用户分别授予访问权限。
访问仅限于用户授权的工作区。
用户可以通过断开应用程序的连接随时删除访问权限。

管理 OAuth 应用

“OAuth 应用”页面显示所有已注册的应用程序。

您可以查看现有应用并删除不再需要的应用程序。

如何删除 OAuth 应用

要删除 OAuth 应用：

登录您的 Astra 账户。
打开账户 → OAuth 应用。
找到您要删除的应用程序。
删除该应用程序。
确认操作。

删除应用后会发生什么？

删除 OAuth 应用时：

无法再发起新的授权请求。
现有访问令牌将被撤销。
已连接的用户将立即失去访问权限。
如果创建了替代应用，用户必须重新连接。

OAuth 应用 vs. API 密钥

应选择哪个选项？

使用下表确定最适合您用例的身份验证方法。

	OAuth 应用	API 密钥
目标用户	客户和最终用户	内部系统和后端服务
是否需要用户授权	是	否
用户同意屏幕	是	否
是否支持多个客户	是	否
凭证类型	可以刷新的短期访问令牌	长期 API 密钥
典型用例	“连接您的 Astra 账户”集成	自动化数据同步或内部工作流程