授权端点
GET/openapi/v1/oauth/auth
发起 OAuth 2.0 授权码流程。在 WebView 中打开此 URL,用户将跳转到 Tencent eSign 授权页完成登录、选择 Space 并授权。
用户点击同意后,服务端将重定向到您的 redirect_uri 并携带授权码 code。将此 code 传给 POST /openapi/v1/oauth/token 即可换取令牌。
两种模式:
- 开放模式(默认):不传 space_id。用户在 授权页自行选择 Space。若 login_hint 邮箱未注册,系统自动静默注册新账号。
- 指定 Space 模式:同时传 space_id 和 login_hint。目标 Space 在服务端锁定,用户无法切换。用户必须已通过 POST /openapi/v1/members/add 预添加至该 Space,否则授权将以 access_denied 拒绝。
必须使用 PKCE(code_challenge_method=S256),不支持 plain。
请求参数
Query 查询参数
client_id必填string
应用的 `client_id`,在 Tencent eSign 控制台创建应用时生成。
response_type必填string
固定填 `code`。
redirect_uri必填string
授权完成后的回调地址,须与控制台注册的值**精确一致**。支持自定义协议(如 `myapp://oauth-callback`)和 HTTPS URL。
code_challenge必填string
`base64url(SHA-256(code_verifier))`,由集成方应用生成。
code_challenge_method必填string
固定填 `S256`,不支持 plain。
state选填string
**强烈建议传入。** 由集成方应用生成的随机串(建议 ≥ 32 字节),回调时原样返回。回调后需校验与本地值一致,防止 CSRF 攻击。
scope选填string
以空格分隔的权限范围。若不传,默认取该应用注册的全部 scope。
login_hint选填string
预填 授权页的邮箱输入框。**开放模式**下,若邮箱未注册,系统自动静默注册新账号。**指定 Space 模式**下,须与 `/members/add` 中预添加的邮箱一致。
space_id选填string
**指定 Space 模式专用。** 传入后,目标 Space 在服务端锁定,用户在 授权页无法切换 Space。需配合 `POST /openapi/v1/members/add` 预添加成员使用。若用户未被预添加,授权将以 `access_denied` 拒绝。
lang选填string
界面语言,可选值 `en`(英语)、`zh-CN`(简体中文)、`zh-HK`(繁体中文)、`id`(印尼语)、`ms`(马来语)、`th`(泰语)、`vi`(越南语)。传入后后端透传给前端 授权页和登录页,用于控制界面语言。不传则默认英文。
响应参数
重定向到 授权页。用户完成授权后回调到 redirect_uri。
授权成功:
{redirect_uri}?code=AUTH_CODE&state=ECHOED_STATEcode 有效期 10 分钟,且只能使用一次。请立即调用 POST /openapi/v1/oauth/token 换取令牌。
用户取消或拒绝授权:
{redirect_uri}?error=access_denied&state=ECHOED_STATE其他错误(如 client_id 无效、redirect_uri 不匹配等):
{redirect_uri}?error=invalid_request&error_description=...&state=ECHOED_STATE