OAuth 接口参考
本页内容
在完成 OAuth 接入流程后,用本页核对授权、令牌刷新与撤销的参数和响应。OAuth 端点使用表单和自己的响应格式,与业务 API 分别处理。
调用前准备
先按OAuth 与终端接入登记客户端,并完成所需的用户授权准备。本页的地址使用网站主域名 https://www.onesignios.com,全程 HTTPS。
public 客户端不保管 Client Secret;confidential 客户端在自己的服务端使用 client_secret_post,将 Secret 放在表单字段。令牌和撤销端点不接受 HTTP Basic、Bearer 或 AccessKey 认证头,也不使用业务 API 的幂等键。除 action 外,业务参数放在表单中。
POST 使用 application/x-www-form-urlencoded,正文最多 16 KiB,字段不可重复。OAuth 表单按标准进行 URL 编码;它与 /api/v1/ 的 JSON 请求分别处理。
查询授权服务器信息
发送 GET https://www.onesignios.com/oauth.php?action=metadata。此请求无需 AccessKey 或用户登录。读取以下信息,并将预期 issuer 绑定到自己的接入配置。
| 字段 | 说明 |
|---|---|
issuer | 授权签发方,值为网站 HTTPS 来源。回调中的 iss 必须与预期值相同。 |
authorization_endpoint | 在系统浏览器打开的用户授权地址。 |
token_endpoint | 交换授权码和刷新令牌的地址。 |
revocation_endpoint | 撤销令牌所关联授权的地址。 |
scopes_supported | 当前协议支持的动作。实际可授权范围还受账号许可、父 API 应用和用户同意限制。 |
code_challenge_methods_supported | 支持 S256。 |
token_endpoint_auth_methods_supported | 支持 client_secret_post 和 none,分别用于 confidential 与 public 客户端。 |
用授权码换取令牌
向 POST /oauth.php?action=token 发送 URL 编码表单。public 与 confidential 客户端都需要 PKCE。
| 字段 | 必填 | 说明 |
|---|---|---|
grant_type | 是 | 固定为 authorization_code。 |
client_id | 是 | 发起授权时使用的客户端 ID。 |
client_secret | confidential 必填 | 从服务端受保护配置读取;public 客户端不填写。 |
code | 是 | 本次回调收到且尚未使用的完整授权码。 |
redirect_uri | 是 | 与原授权请求完全相同的回调地址。 |
code_verifier | 是 | 本次授权开始前保存的原 verifier。 |
grant_type=authorization_code
client_id=<已登记客户端ID>
code=<本次回调的授权码>
redirect_uri=https%3A%2F%2Fclient.example.com%2Foauth%2Fcallback
code_verifier=<原verifier>上面按行展示字段以方便阅读。实际发送时使用表单编码器将字段连接为 key=value&key=value,不要原样发送多行文本。confidential 客户端另加 client_secret。
成功时 HTTP 200 直接返回下面的对象,不包含业务 API 的 data 包装。响应头提供 X-Request-Id。
{
"access_token": "<接口返回的完整访问令牌>",
"token_type": "Bearer",
"expires_in": 300,
"refresh_token": "<接口返回的完整刷新令牌>",
"scope": "enterprise:ReadApps"
}expires_in 为访问令牌的剩余秒数,最多 300 秒。保存整组令牌、取得时间和实际 scope;用户可能只同意了所请求权限的一部分。刷新令牌受原授权和父凭据期限约束,刷新不会延长用户授权期限。
刷新令牌
仍向 POST /oauth.php?action=token 发送表单,字段如下。刷新时不提交 code、redirect_uri 或 code_verifier。
| 字段 | 必填 | 说明 |
|---|---|---|
grant_type | 是 | 固定为 refresh_token。 |
client_id | 是 | 原客户端 ID。 |
client_secret | confidential 必填 | 仅 confidential 客户端从服务端配置读取。 |
refresh_token | 是 | 当前持久保存、尚未使用的完整刷新令牌。 |
- 同一授权使用串行刷新,防止多个线程或服务实例同时消费原令牌。
- 成功后原子替换访问令牌与刷新令牌,并让所有调用方使用新值。原访问令牌也会失效。
- 刷新令牌或授权码被再次使用时,平台可能撤销这一整组授权。网络超时后不要自动重放旧值;无法可靠取得新令牌时,结束原会话并重新发起用户授权。
调用业务 API 时使用 Authorization: Bearer <access_token>。不发送 AccessKey 签名头;POST 业务请求仍需要 JSON 和原业务幂等键,见认证请求头对照。
撤销授权
向 POST /oauth.php?action=revoke 发送表单。
| 字段 | 必填 | 说明 |
|---|---|---|
client_id | 是 | 持有此授权的客户端 ID。 |
client_secret | confidential 必填 | 仅 confidential 客户端使用。 |
token | 是 | 本次要结束的授权所关联的完整访问令牌或刷新令牌。 |
token_type_hint | 否 | 兼容提示字段,通常可省略;它不改变实际令牌的识别和撤销范围。 |
撤销成功返回 HTTP 200 和 {}。平台会撤销对应整组用户授权,关联的访问令牌和刷新令牌一并失效。未知、已失效或不属于该客户端的令牌也可以返回相同空对象,因此不能用此响应判断令牌是否曾经存在。
接收成功后清理本地令牌并停止调用。用户也可以在开发者中心撤销自己的第三方授权。更换客户端配置、撤销父凭据或收缩权限后,实际访问范围会相应变化。
处理授权错误
令牌和撤销端点的错误使用 OAuth 格式:error 是字符串,error_description 供人阅读,request_id 用于排查;不要读取 error.code。
{
"error": "invalid_grant",
"error_description": "授权码或刷新令牌无效",
"request_id": "11111111111111111111111111111111"
}| 情况 | 处理方式 |
|---|---|
invalid_request | 检查方法、表单类型、字段完整性和重复字段;授权请求还需核对精确回调地址与 state。 |
invalid_client | 核对客户端 ID、类型与服务端 Client Secret。public 客户端不传 Secret。 |
invalid_scope | 从元数据选择支持的动作,核对账号许可、父 API 应用与本次用户同意范围。 |
invalid_grant | 核对原授权码、PKCE 和令牌是否过期或已消费;需要重新授权时,让用户重新确认。 |
unsupported_grant_type | grant_type 使用 authorization_code 或 refresh_token。 |
access_denied | 处理用户拒绝,或核对账号、客户端审核状态、Origin 与原授权是否仍有效。结合 HTTP 状态判断。 |
HTTP 429 或 temporarily_unavailable | 限制请求频率,保存请求标识;等待服务恢复。已经可能消费的授权码或刷新令牌不做盲目重放。 |
授权页面返回 HTML 或浏览器重定向,不按 JSON 接口解析。浏览器直连只适用于已批准的 public 客户端来源。日志中保留状态与请求标识,隐藏 code、verifier、Secret 和令牌。