Authorization Code + 自定义重定向流程

对于代表已登录用户执行操作并在你自己的域名上接收 OAuth 回调的 Web 应用程序，请使用 Authorization Code + 自定义 HTTPS 重定向流程。它使用带 PKCE 的 Authorization Code、完全匹配的 HTTPS 重定向 URI，以及为服务器端机密客户端提供的可选客户端密钥。

如果你尚未了解前提条件、网络访问和安全模型，请先查看快速入门指南。

你将要做什么

创建 OAuth 应用：在 Prevu3D 中用你的 HTTPS 回调 URL 注册一个 Web 应用
配置用户访问权限：确保登录用户能够访问其所需的数据
使用 PKCE 授权：引导用户通过浏览器同意页面
用代码交换令牌：用授权码换取访问令牌
查找你的 API URL：发现你组织的基础 URL（因区域而异）
进行首次调用：使用简单请求测试连接

步骤 1：创建你的 OAuth 应用

登录 Prevu3D 平台。
前往 Settings → OAuth。
点击以创建新应用。
启用 Authorization Code flow。
将 Native Application 保持关闭。
输入你的重定向 URI，例如 https://app.example.com/oauth/callback。它必须是带完全限定域名的 HTTPS，并且在授权和令牌交换时必须完全匹配。
如果你的应用可以在服务器端存储客户端密钥，可以选择启用客户端密钥。仅在浏览器中运行的公共客户端不应使用密钥。
复制并安全存储你的 Client ID（如果生成了密钥，也一并存储）。

步骤 2：配置用户访问权限

此流程以已登录用户身份调用 API，而非服务用户。这涵盖安全模型的第 2 层和第 3 层：用户可以看到哪些节点（内容访问），以及它可以对它们做什么（角色 / 权限访问）。

确保将要登录的用户对你的用例所需节点（组织、部门、站点等）具有内容访问权限。
确保该用户在这些节点上拥有一个角色，具备你的集成所需的权限（读取、编辑、管理等）。

在同意屏幕上，用户还会选择要授权哪个组织。用户在此处批准的作用域配置第 1 层。

步骤 3：使用 PKCE 授权

在打开同意页面之前，生成三个值：

值	方法
`code_verifier`	随机字符串，43 到 128 个字符
`code_challenge`	无填充的 `BASE64URL(SHA256(code_verifier))`
`state`	随机字符串；当重定向返回时验证它

打开用户的浏览器至同意页面。

同意 URL： https://cloud.prevu3d.com/oauth

查询参数（全部必需）：

参数	值
`response_type`	`code`
`code_challenge_method`	`S256`
`client_id`	你的 Client ID
`redirect_uri`	你注册的 HTTPS 回调 URI（完全匹配，除非已注册否则无尾部斜杠）
`scopes`	每个作用域一个，例如 `scopes=read:basic&scopes=read:hierarchy`
`code_challenge`	上面的 PKCE 挑战
`state`	你的随机 state 值

用户登录并点击 Allow 后，浏览器重定向到你的回调：

https://app.example.com/oauth/callback?code={authorization_code}&state={state}

如果用户拒绝访问，你会收到 ?error=access_denied。授权码在 60 秒后过期，因此请立即交换它们。

步骤 4：用代码交换访问令牌

端点： POST https://cloud-api.prevu3d.com/oauth/token

标头： Content-Type: application/x-www-form-urlencoded

正文：

字段	值
`grant_type`	`authorization_code`
`client_id`	你的 Client ID
`code`	来自重定向的代码
`redirect_uri`	步骤 3 中使用的相同 URI
`code_verifier`	原始的 PKCE verifier
`client_secret`	仅当你的应用拥有密钥时

你可以在正文中发送 client_id 和 client_secret，或使用 Authorization: Basic base64(client_id:client_secret)。

示例响应：

{
  "hasError": false,
  "expires_in": 86400,
  "access_token": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "..."
}

保存两个令牌。使用 access_token 进行 API 调用。当它过期时，用 grant_type=refresh_token 和你存储的 refresh_token 请求新令牌。

步骤 5：获取你的 API 基础 URL

调用发现端点以获取你组织的 apiUrl。不要硬编码区域 URL。

端点： GET https://cloud-api.prevu3d.com/oauth/api-info

标头： Authorization: Bearer <your_access_token>

示例响应：

{
  "user": { "..." : "..." },
  "organization": {
    "id": "217ebd23-ec54-4af0-a6d6-4a441a6d1966",
    "name": "Test Organization"
  },
  "scopes": ["read:basic", "read:hierarchy"],
  "apiUrl": "https://api-ue1.prevu3d.com/realityconnect-api"
}

将 apiUrl 值用作你所有 API 调用的基础。另请注意 organization.id，许多端点都需要它。

步骤 6：进行你的首次 API 调用

你现在拥有所需的一切：访问令牌和你的基础 URL。让我们进行一个简单的请求来检索你组织的部门：

GET {apiUrl}/v1/nodes/{organization_id}/browse
Authorization: Bearer <your_access_token>

使用真实值的示例：

GET https://api-ue1.prevu3d.com/realityconnect-api/v1/nodes/217ebd23-ec54-4af0-a6d6-4a441a6d1966/browse HTTP/1.1
Authorization: Bearer eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9...

包含部门列表的成功响应确认你的集成正在正确工作。

故障排除

症状	需要检查什么
在同意或令牌交换时出现 Redirect URI mismatch	`redirect_uri` 必须与 OAuth 应用上注册的值逐字符匹配
保存应用时出现 Invalid OAuth redirect URI	使用 `https`、有效的域名，注册的 URI 中不含查询字符串或片段
Bad OAuth application secret	仅当应用是用密钥创建的时才包含 `client_secret`
Grant exchange expired	授权码在 60 秒后过期；重新启动流程
RCAPI 调用出现 403	用户可能缺少该操作的内容访问权限、节点角色或 OAuth 作用域

需要为桌面应用或 CLI 使用回环重定向吗？请改用 Native Application 流程。

下一步是什么？

Native Application 流程，用于无自定义域名的本地主机 / PKCE
Client Credentials 流程，用于服务器到服务器访问
交互式 API 参考，查看完整的端点目录