令牌接口
接口描述

天翼开放平台令牌接口用于获取最终的授权访问令牌(Accesss Token,简称AT)。该接口可用于三种不同的应用场合:

应用场合一:在oAuth 2.0的标准Authorization Code授权模式(简称AC授权模式)下,当应用的服务器端获得了AC授权码之后,其可以利用该接口,凭借AC授权码来换取获得最终的AT访问令牌

应用场合二:在oAuth 2.0的标准Client Credentials授权模式(简称CC授权模式)下,应用可凭借自身的应用ID和应用密钥,通过调用该接口,直接获得无需用户授权的AT访问令牌(User-Independent Access Token,简称UIAT)。

不同于普通的AT令牌,UIAT令牌其只能用于调用无需用户授权的开放API接口,如获取音乐榜单等;而普通的AT令牌则既可用于调用需要用户授权的开放API接口,又可用于调用无需用户授权的开放接口。UIAT令牌多用于无需用户登录的合作应用场合,尽管其使用范围较普通AT令牌相对受限,但二者的数据形式是基本一致的。

应用场合三:在普通AT令牌或者是UIAT令牌过期的情况下,合作应用可调用天翼开放平台令牌接口,实现对访问令牌的更新。

天翼开放平台令牌接口使用输入参数grant_type区分上述三种应用场合。当grant_type取值为”authorization_code”时,其表示当前的调用场合为应用场合一,天翼开放平台令牌接口将返回普通AT令牌;当grant_type取值为”client_credentials”时,其表示当前的调用场合为应用场合二,天翼开放平台令牌接口将返回UIAT令牌;当grant_type取值为”refresh_token”时,其表示当前调用场合为应用场合三,天翼开放平台令牌接口将返回更新之后的普通AT令牌或UIAT令牌。

承载协议
HTTPS
请求方式
POST
调用地址

https://oauth.api.189.cn/emp/oauth2/v3/access_token

请求参数
  • grant_type”authorization_code”时:

参数名

必选

类型

说  明

grant_type

true

string

此值必须为“authorization_code”

code

true

string

调用EMP授权接口所获得的code值

app_id

true

string

应用注册时分配的应用ID

app_secret

true

string

申请应用时分配的应用密钥

redirect_uri

true

string

该值必须与EMP授权接口输入参数保持一致

state

false

string

用于跟踪调用状态。在响应消息中将会原封不动的返回该值

  • grant_type”client_credentials”时:

参数名

必选

类型

说  明

grant_type

true

string

此值必须为“client_credentials”

app_id

true

string

应用注册时分配的应用ID

app_secret

true

string

申请应用时分配的应用密钥

state

false

string

用于跟踪调用状态。在响应消息中将会原封不动的返回该值

scope

false

string

权限列表,保留字段,默认为空

  • grant_typerefresh_token时:

参数名

必选

类型

说  明

grant_type

true

string

此值必须为“refresh_token”

refresh_token

true

string

用于刷新访问令牌所需的更新令牌

app_id

true

string

应用注册时分配的应用ID

app_secret

true

string

申请应用时分配的应用密钥

state

false

string

用于跟踪调用状态。在响应消息中将会原封不动的返回该值

scope

false

string

权限列表,保留字段,默认为空

应答参数

EMP令牌接口在调用成功的情况下,将返回所获取到的访问令牌及其所对应的更新令牌。EMP令牌接口应答参数由公共应答参数和额外应答参数构成。

  • 公共应答参数

参数名

必选

类型

说  明

res_code

true

unsigned int

标准返回码。返回0表示成功;其他表示调用出错或异常,返回值的具体定义详见第6节

res_message

true

string

返回码描述信息

state

false

string

与请求参数中state的值一致

  • 额外应答参数:当成功应答

参数名

必选

类型

说  明

access_token

true

string

获取到的访问令牌(AT或UIAT)

expires_in

true

string

访问令牌的有效期(以秒为单位)

refresh_token

true

string

获取到的刷新令牌,与获取到的访问令牌相对应

p_user_id

false

string

天翼帐号的唯一标志,用于标识与access_token字段所对应的用户;当grant_type输入参数为client_credentialsrefresh_token时,将不返回该字段

scope

false

string

权限列表,保留字段,默认为空

  • 额外应答参数:当返回错误时

调用范例

grant_type”authorization_code”时:

请求范例:AC授权模式下的AT访问令牌获取

https://oauth.api.189.cn/emp/oauth2/v3/access_token

使用POST方法传参:

grant_type=authorization_code&

code=0987654321&

app_id=1234567890&

app_secret=abcdefghijk&

redirect_uri=http://www.example.com/oauth_redirect

成功应答范例:返回AT访问令牌

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache


{

"access_token":"ACCESS_TOKEN",

"expires_in":9999,

"refresh_token":"REFRESH_TOKEN",

“open_id”:”35123456789”,

“res_code”:0,

“res_message”:”Success”

}

失败应答范例:

HTTP/1.1 400 Bad Request

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache


{

          “res_code”:10009,

          “res_message”:”Access denied”

}

grant_type”client_credentials”时:

请求范例:CC授权模式下的UIAT访问令牌获取

https://oauth.api.189.cn/emp/oauth2/v3/access_token

使用POST方法传参:

grant_type=client_credentials&

app_id=1234567890&

app_secret=abcdefghijk

成功应答范例:返回UIAT访问令牌

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache


{

"access_token":"USER_INDEPENDENT_ACCESS_TOKEN",

"expires_in":9999,

“res_code”:0,

“res_message”:”Success”

}

失败应答范例:

HTTP/1.1 400 Bad Request

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache


{

          “res_code”:10009,

          “res_message”:”Access denied”

}

grant_typerefresh_token时:

请求范例:某访问令牌更新

https://oauth.api.189.cn/emp/oauth2/v3/access_token

使用POST方法传参:

grant_type=refresh_token&

refresh_token="REFRESH_TOKEN"&

app_id=1234567890&

app_secret=abcdefghijk

 

成功应答范例:返回新的访问令牌

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache


{

"access_token":"ACCESS_TOKEN",

"expires_in":9999,

"refresh_token":"REFRESH_TOKEN",

“res_code”:0,

“res_message”:”Success”

}

 

失败应答范例:

HTTP/1.1 400 Bad Request

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache


{

          “res_code”:10009,

          “res_message”:”Access denied”

}
其他
一、调用失败结果如下:
1 未知错误 Unknown error
2 服务暂不可用 Service temporarily unavailable
3 未知的方法 Unsupported openapi method
4 接口调用次数已达到设定的上限 Open api request limit reached
5 请求来自未经授权的IP地址 Unauthorized client IP address
6 无权限访问该用户数据 No permission to access user data
7 来自该refer的请求无访问权限 No permission to access data for this referer
100 请求参数无效 Invalid parameter
101 api key无效 Invalid API key
104 无效签名 Incorrect signature
105 请求参数过多 Too many parameters
106 未知的签名方法 Unsupported signature method
107 timestamp参数无效 Invalid/Used timestamp parameter
109 无效的用户资料字段名 Invalid user info field
110 无效的access token Access token invalid or no longer valid
111 access token过期 Access token expired
210 用户不可见 User not visible
211 获取未授权的字段 Unsupported permission
212 没有权限获取用户的email No permission to access user email
800 未知的存储操作错误 Unknown data store API error
801 无效的操作方法 Invalid operation
802 数据存储空间已超过设定的上限 Data store allowable quota was exceeded
803 指定的对象不存在 Specified object cannot be found
804 指定的对象已存在 Specified object already exists
805 数据库操作出错,请重试 A database error occurred. Please try again
900 访问的应用不存在 No such application exists
1121 用户不存在
1157 Avino不能为空
2029 该帐号没有对应的通讯权限,如电话、短信、电话会议。