oauthTokenV2：换取或刷新 OAuth token
oauthTokenV2：换取或刷新 OAuth token
功能说明
在 H5 授权完成后，用授权码换取终端用户 OAuth access token，或在过期前用 refresh_token 刷新。本接口使用 form-urlencoded 请求体与 HTTP Basic 鉴权（OAuth 项目 Access Key / Secret Key），不是多数 Open API 使用的标准 JSON 公共请求体（含 system 对象）。
授权码回调流程见 OAuth 2.0 授权。
请求地址
POST https://openapi-[DataCenter].easy4ip.com/openapi/oauthTokenV2
[DataCenter] 替换为开发者账号所属数据中心（见 开发规范）。
鉴权
| 请求头 | 值 |
|---|---|
Authorization | Basic + Base64(ProjectAccessKey:ProjectSecretKey) |
Content-Type | application/x-www-form-urlencoded |
参考：RFC 2617 §2。
grant_type：authorization_code
用回调 URL 中的授权码换取 token。
表单参数
| 参数 | 必填 | 说明 |
|---|---|---|
| grant_type | 是 | authorization_code |
| code | 是 | 回调 URL 中 code 参数 |
| redirect_uri | 否 | 可选。与 OAuth 项目控制台配置的回调 URL 一致。开放平台换 token 接口不校验该字段；仅在客户端或授权服务要求时提交。 |
请求示例
POST /openapi/oauthTokenV2 HTTP/1.1
Host: openapi-fk.easy4ip.com
Authorization: Basic <base64(ProjectAccessKey:ProjectSecretKey)>
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=XXXXXXXXXXXXXXXXXX&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
grant_type：refresh_token
在 expires_in 到期前刷新 access token。
表单参数
| 参数 | 必填 | 说明 |
|---|---|---|
| grant_type | 是 | refresh_token |
| refresh_token | 是 | 上次成功响应中的 refresh_token |
请求示例
POST /openapi/oauthTokenV2 HTTP/1.1
Host: openapi-fk.easy4ip.com
Authorization: Basic <base64(ProjectAccessKey:ProjectSecretKey)>
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=QWU3723JDDUFH2382
响应（成功）
HTTP 200，Content-Type: application/json;charset=UTF-8，Cache-Control: no-store，Pragma: no-cache。
| 字段 | 类型 | 说明 |
|---|---|---|
| access_token | String | 终端用户 access token（Ot_ 前缀），bearer |
| token_type | String | bearer |
| expires_in | Number | 有效期（秒），7200 |
| refresh_token | String | 用于下次刷新 |
| scope | String | 当前为 all |
响应示例
{
"access_token": "Ot_xxxxxxxxxxxxxxxxxx",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "QWU3723JDDUFH2382",
"scope": "all"
}
错误响应
本接口采用 OAuth 2.0 token 错误格式，不是标准 Open API 的 result 响应结构。失败时 HTTP 状态码常为 200 或 400，响应体为带 error 字段的 JSON。
error | 说明 |
|---|---|
invalid_request | 缺少或空的 grant_type、code、refresh_token；Authorization 头格式错误 |
invalid_client | OAuth 项目 Access Key / Secret Key 无效，或换 token 失败 |
unsupported_grant_type | grant_type 不是 authorization_code 或 refresh_token |
相关
错误码
网关与鉴权（SN / TK / OP）
| 错误码 | 错误码说明 | 下一步 |
|---|---|---|
SN1001 | 签名校验异常 | 按 HTTP 开发规范 核对 sign |
TK1002 | token 无效或过期 | 重新获取 accessToken |
OP1002 | 缺少必填参数 | 补必填字段 |
OP1003 | 参数不合法 | 按本页参数表核对 |
OP1009 | 权限不足 | 核对 token 与设备绑定/分享权限 |
OP1013 | 接口总次数超限 | 降低调用频率 |
OP1014 | 接口日限额超限 | 见 接口调用限额 |
DV1007 | 设备离线 | 等设备上线 |
更多见 错误码 · OP/SN/TK。
子账号（SUB）
| 错误码 | 错误码说明 | 下一步 |
|---|---|---|
SUB1001–SUB1002 | 子账号无接口权限 | 在 addPolicy 中补策略 |
SUB1005 | 子账号 token 过期 | 重新 subAccountToken |
SUB1006 | 子账号与设备无授权 | 核对 Resource 与设备序列号 |
SUB1008 | 子账号未绑定应用 | 先创建并绑定子账号 |
更多见 错误码 · SUB。