账户财务 > 使用文档 > 刷新账户管理凭证

刷新账户管理凭证

最近更新时间: 2017-02-21 17:16:58

描述

账户管理凭证（AccessToken，下同）本身具有有效期，通常为 3600 秒（1 小时）。
凭证失效后，七牛服务器会返回类似如下内容的错误提示：

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store

{
    "error": "expired_token", 
    "error_code": 9,
    "error_description": "Invalid Access Token: LvIaQm6bTrgtp6, it has been expired, you can pass the Refresh Token for get new one!"
}

此时凭证无法继续使用，有两种处理办法：

使用username和password重新申请授权；
使用授权时获得的RefreshToken重新申请授权，即本文档介绍的方法。

请求语法

POST /oauth2/token HTTP/1.1
Host: acc.qbox.me
Content-Type: application/x-www-form-urlencoded

<OAuthTokenRequestParams>

访问权限

无。

头部信息

头部名称	必填	说明
Host	是	固定为`acc.qbox.me`，必须以 HTTPS 方式访问。
Content-Type	是	固定为`application/x-www-form-urlencoded`。

请求参数

请求参数以表单形式组织，作为请求内容提交，格式如下：

grant_type=refresh_token&refresh_token=<UrlEncodedRefreshToken>

参数名称	必填	说明
grant_type	是	固定为`refresh_token`。
refresh_token	是	上次授权时得到的 RefreshToken。

响应

响应语法

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

<OAuthTokenResponseContent>

头部信息

头部名称	必填	说明
Content-Type	是	正常情况下该值将被设为`application/json`，表示返回 JSON 格式的文本信息。
Cache-Control	是	正常情况下该值将被设为`no-store`，表示不缓存。

响应内容

■ 如果请求成功，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

{
    "access_token": "<AccessToken string>",
    "expires_in": <AccessTokenDuration int64>,
    "refresh_token": "<RefreshToken string>"
}

字段名称	必填	说明
access_token	是	即 AccessToken，用于后续调用。
expires_in	是	AccessToken 的有效期，单位：秒，通常为 3600 秒。
refresh_token	是	刷新 AccessToken 有效期的凭证，有效期 30 个自然日。

■ 如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

{
    "error": "<ErrTitle string>",
    "error_code": <ErrCode int>,
    "error_description": "<ErrMsg string>"
}

HTTP 状态码	error_code	error	error_description
405	1	invalid_request_method	请求方式错误，非预期的 POST 请求。
400	2	invalid_client	client_id, client_secret 参数无效。
400	3	invalid_token	错误的、非预期的 AccessToken 或 RefreshToken。
400	4	invalid_email	E-Mail 地址格式不正确。
400	5	invalid_grant_type	grant_type 参数值错误或不在服务端所支持的列表中。
400	6	invalid_without_params	缺少相应的必要参数。
400	7	invalid_empty_params	参数的值不能为空。
400	8	invalid_bad_request	错误的请求。
401	9	expired_token	提供的 AccessToken 或 RefreshToken 已过期 (视具体情况而定)。
409	10	record_exists	记录已经存在。
401	11	failed_authentication	验证失败, 比如用户名或密码错误。
417	12	failed_request	请求失败。
403	13	unauthorized_client	应用未授权。
400	14	record_not_found	记录不存在，比如 email 未注册等等。
401	15	permission_denied	缺少操作权限，跟用户类型有关。

响应状态码

HTTP 状态码	含义
200	授权成功。
4xx	参考错误消息表。
599	服务端操作失败。
如遇此错误，请将完整错误信息（包括所有 HTTP 响应头部）通过邮件发送给我们。

附注

每次刷新后，RefreshToken 有效期都会重新计算；
RefreshToken 本身也失效后，只能使用username和password重新申请授权。

以上内容是否对您有帮助？