当开放平台的应用需要获取商家或者用户数据(商品、订单信息等),需要引导用户先使用淘宝帐号登录并授权您的应用,用户授权成功平台会返回用户授权码 Sessionkey(即access_token),之后调用接口时传入对应用户的授权码就可以获取到该用户的数据。
注意:
1)对于开发阶段sessionkey的快速获取,可以使用官方工具获取sessionkey,点击使用;通过授权工具重新授权会刷新授权有效时间。
2)授权以后的sessionkey是有有效时间的,可以通过 授权Sessionkey解析 查询该次授权的有效时间,更多授权工具可以使用 授权常用工具 。
3)文档描述的用户授权操作仅适用于web应用授权使用,如果是手机淘宝/天猫客户端小程序开发,请参考《授权场景》。
4) sessionkey是根据应用appkey与授权账号生成的,使用哪个商家的淘宝账号授权,就仅能获取该商家的数据。
以下是关于授权的具体技术实现方案,开发者可以根据需要选择合适的授权方式。
此流程需要您有自己的web服务器,能够保存应用本身的密钥以及状态,可以通过https直接访问淘宝的授权服务器。适用于服务多商家或多用户频繁使用软件的场景。
授权过程分为两个步骤:
1)获取授权码: 通过用户授权获取授权码code。
正式环境:拼接以 https://oauth.taobao.com/authorize 开头的url。
2)获取访问令牌:用上一步获取的 code 和应用密钥(AppSecret)通过POST方式换取accesstoken(即sessionkey)。
正式环境:拼接以 https://oauth.taobao.com/token 开头的url。
第三方应用授权的流程如下所示:
要在您的应用中使用淘宝开放产品的接口能力,您需要先去淘宝开放平台(https://open.taobao.com/),创建登记您的应用,这里不再详细展开介绍,请参考《新手指南》。
拼接规则示例:
示例中的 client_id 和 redirect_uri 需要替换成您创建应用的实际数据。
client_id :传入appkey,查找路径:【控制台】-【开发】-【我的应用】-【应用管理】-【概览】-【AppKey】,AppSecret 也在此处;
redirect_uri :传入回调地址, 查找路径:【控制台】-【开发】-【我的应用】-【应用管理】-【应用设置】-【基本信息】-【回调URL】。(仅适合非小程序式应用,即一站式电商后台)
拼接授权URL相关参数说明: |
|||
名称 |
是否必选 |
参数值 |
参数释义 |
client_id |
必选 |
12345678(八位) |
即appkey,创建应用时获得。 |
response_type |
必选 |
code / token |
授权类型 ,值为code / token。 |
redirect_uri |
必选 |
填写应用注册时回调地址域名 |
redirect_uri 指的是应用发起请求时,所传的回调地址参数,在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致 。 |
state |
可选 |
可自定义,如1212等 |
维持应用的状态,传入值与返回值保持一致。 |
view |
可选 |
可选web / tmall / wap其中一种,默认为web |
Web 对应PC端(淘宝logo)浏览器页面样式;Tmall 对应天猫的浏览器页面样式;Wap 对应无线端的浏览器页面样式。 |
force_auth |
可选 |
true,如force_auth=true |
在授权url中加 force_auth=true,不管授权是否有效都会弹授权页面,用户登陆授权以后有效时间会刷新。 |
from_site |
可选 |
fuwu,如from_site=fuwu |
在授权url加from_site=fuwu,用户已登录且授权有效情况下会直接跳转回调,不会弹授权页面,授权时间不刷新。 |
引导用户通过浏览器访问以上授权url,将弹出如下登录页面。用户输入淘宝帐号、密码,点“授权并登录”按钮,即可进入授权页面;若已是登录状态,点“授权并登录'按钮,即可登录授权页面。
此步骤,用哪个商家的淘宝账号登录授权,那获取的 sessionkey只能用来获取该商家的数据,不能获取其他商家数据。
对于品牌旗下多个淘宝店铺场景,可以参考 多店铺管理 场景, 每个店铺账号也必须分别进行登录授权,获取自己店铺的sessionkey。
用户授权登录后,TOP会将授权码 code 返回到回调地址URL,开发者可以获取并使用该 code 换取 access_token。
1)code 有效期是30分钟,超过30分钟未使用,需要重新按授权流程获取;
2)code 只能使用一次,使用后 需要重新按授权流程获取。
3)发布到 服务市场 的应用(如购物应用的用户),在应用上线后,通过【我的订单】-直接点击【使用】,系统会自动跳转到授权页面,因此不需要进行第二步拼接URL,只需注意获取code即可。
方式1 调用API接口获取(推荐)
通过 taobao.top.auth.token.create API接口获取 access_token(授权令牌).
授权有效期通过 expires_in 返回,请自行保存该数据,授权到期前,重新授权获取新的sessionkey,避免使用过期的sessionkey调用接口导致isv报错。(详细介绍见下文名词解释中“授权时长”) ,也可以通过 授权session解析工具,查询sessionkey有效期和授权用户信息,提前判断。
API调用服务请参考《API调用方法详解》,返回参数结果示例如下。
换取access_token 返回参数 说明: (以下参数,调用接口taobao.top.auth.token.create 时会返回,请自行保存数据,避免使用过期的token导致报错) |
|||
Key |
类型 |
示例 |
说明 |
access_token |
string |
2YotnFZFEjr1zCsicMWpAA |
Access token |
token_type |
string |
Bearer |
Access token的类型目前只支持bearer |
expires_in |
number |
10(表示10秒后过期) |
Access token过期时间 |
refresh_token |
string |
2YotnFZFEjr1zCsicMWpAA |
Refresh token,可用来刷新access_token |
re_expires_in |
number |
10(表示10秒后过期) |
Refresh token过期时间 |
r1_expires_in |
number |
10(表示10秒后过期) |
r1级别API或字段的访问过期时间; |
r2_expires_in |
number |
10(表示10秒后过期) |
r2级别API或字段的访问过期时间; |
w1_expires_in |
number |
10(表示10秒后过期) |
w1级别API或字段的访问过期时间; |
w2_expires_in |
number |
10(表示10秒后过期) |
w2级别API或字段的访问过期时间; |
taobao_user_nick |
string |
商家账号 |
淘宝账号名(前台类应用获取的为混淆的账号名) |
taobao_user_id |
string |
706388888 |
淘宝帐号对应id |
taobao_open_uid |
string |
SDJFKLSJFlJSDKF |
淘宝账号对应openUid加密 |
sub_taobao_user_id |
string |
2343535 |
淘宝子账号对应id |
sub_taobao_user_nick |
string |
测试账号test:123 |
淘宝子账号 |
方式2 拼装服务端请求。
如果你对 linux 比较熟悉,可以利用 curl 命令体验一下如何获取访问令牌。注意替换一下 "code="后面的授权码,其他参数也根据实际情况进行替换。
curl -i -d
"code=OxlukWofLrB1Db1M6aJGF8x2332458&grant_type=authorization_code&client_id=11111111&client_secret=69a1a2a3a469a1469a14a9bf269a14&redirect_uri=http://www.oauth.net/2/"https://oauth.taobao.com/token
换取access_token请求参数说明: |
|||
名称 |
是否必选 |
参数值 |
参数释义 |
client_id |
必选 |
等同于AppKey,创建应用时获得。 |
|
client_secret |
必选 |
等同于AppSecret,创建应用时获得。 |
|
grant_type |
必选 |
authorization_code |
授权类型 ,值为authorization_code。 |
code |
必选 |
上一步获取code得到。 |
|
redirect_uri |
必选 |
填写应用注册时回调地址域名。redirect_uri指的是应用发起请求时,所传的回调地址参数,在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致 。 |
|
state |
可选 |
可自定义,如1212等;维持应用的状态,传入值与返回值保持一致。 |
|
view |
可选 |
可选web、tmall或wap其中一种,Web对应PC端(淘宝logo)浏览器页面样式;Tmall对应天猫的浏览器页面样式;Wap对应无线端的浏览器页面样式。 |
对于应用程序,可以参考如下代码获取访问令牌:
PHP 示例: |
JAVA 示例: |
C# 示例: string url = "https://oauth.taobao.com/token"; Dictionary<string, string> props = new Dictionary<string, string>(); props.Add("grant_type", "authorization_code"); props.Add("code","code"); props.Add("client_id","test"); props.Add("client_secret", "test"); props.Add("redirect_uri", "test"); props.Add("view", "web"); string s = ""; try { WebUtils webUtils = new WebUtils(); s = webUtils.DoPost(url, props, 30000, 30000); } catch (IOException e) { |
然后从里面提取access_token字段,返回结果内容示例:
{ |
客户端应用授权方式,适合ISV应用没有独立的web Server,需要借助浏览器或者JS脚本访问授权服务器,或者用户手动复制页面上的sessionkey输入到客户端。一般适用于自研应用或者低频使用的场景。
第三方应用授权的流程如下所示。
同上第一步,详情参考上文。
获取授权码: 拼接以https://oauth.taobao.com/authorize开头的url 。
拼接规则样例:
https://oauth.taobao.com/authorize?response_type=token&client_id=11111111&state=1212&view=web
相关参数位置及说明,同上第二步。
这一步同上授权方式,引导用户访问授权URL进行授权,如下。
此处上图页面点授权后,TOP会直接将access_token 返回到淘宝默认页面(和 Server-side flow 先返回code 再换access_token方式不同)
需要用户手动复制sessionkey,或者使用JS脚本(if(window.location.hash!=""){alert(window.location.hash)})可以获取回调页面#后面的字段,从而获取到授权码。返回参数示例如下图。
注意:
此处参数返回除 top_sign 外,同Server-side flow授权返回参数相同,这里不再详细描述,具体可参考 Server-side flow 里面的说明。返回参数中的top_sign 是系统生成签名参数,使用 Client-side flow 方式授权需要对该参数进行一致性验证。
可选,即验证返回参数和 top_sign 是否一致。如上返回参数中,把#号之后除 top_sign外所有key和value按照参数的首字母顺序排列,以 key1+value+key2+value....的方式拼接在一起,再在其前后加上的AppSecret。
(如AppSecret=69a1469a1469a1469a14a9bf269a14),然后转成utf-8编码,接着进行md5加密,最后全部转大写即可。md5(utf-8:AppSecret+k1+v1+k2+v2+...+kn+vn + AppSecret)。如以下返回参数,取 # 号之后的参数进行拼接并首尾加上AppSecret后得到如下结果:69a1469a1469a1469a14a9bf269a14access_token6101227f5e8c230696ac93a77b3de7daacb154c6ad98106263664221token_typeBearerexpires_in86400refresh_token6100627e3f9202c0960a6ab5bfd704939c91635892c70dd263664221re_expires_in86400r1_expires_in86400r2expires_in86400taobao_user_id263664221taobao_user_nick%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B717w1_expires_in86400&w2_expires_in86400&state121269a1469a1469a1469a14a9bf269a14
进行md5加密(参考API调用示例代码)并转化成大写后得到:3429C556FCD3F3FC52547DD31021592F ,和top_sign 一致。
目前只有订购类服务商应用可以刷新授权时间, 其他的固定授权时长的应用类型(如,商家后台系统和新业务这类自研型应用无法使用),必须重新登陆授权生成新sessionkey延长授权时间,非订购类应用不支持刷新授权。
通过授权获取的refresh_token(前置条件:re_expires_in>0),可用来刷新access token 的 r2 时长。由于r1 或w1 通常同订购时长一致,一般不需刷新,w2必须通过重新授权给予延长,故 refresh_token 一般仅用于r2 有效时长的延长。
查看API对应的安全等级,请点击《API安全等级》。
方式1:
通过 taobao.top.auth.token.refresh API接口刷新token,每次刷新后原来refresh_token作废,都要更新成最新返回的refresh_token用于下次刷新。(api服务参考《API调用方法详解》)
方式2:
以下为基于sdk的java示例,其它语言可参考token获取方法,是类似的,同时测试时,需把test参数换成自己应用实际对应的值。
import java.io.IOException; |
以上把responseJson 转化为对象,或者直接从里面提取access_token字段以及新的刷新令牌。refresh_token返回结果内容示例:
{ |
AccessToken即用户授权后颁发的SessionKey,也称为数据加密密钥或者工作密钥,当您调用淘宝开放平台涉及用户隐私数据的API接口时,需要传递TOP颁发给应用的授权信息(session_key参数),才能成功调用。
例如,调用 taobao.user.buyer.get API获取买家信息,要求ISV应用必须先得到商家用户授权,获取相关session_key,传递相关参数,才能查询到买家信息。如下图所示。
为了更加灵活地对淘宝开放平台开放的数据进行安全管控, 降低用户数据泄露或者被恶意修改的风险。淘宝开放平台对API或者API字段打了R1,R2,W1,W2四类安全级别的标记,和对开发者的应用打了0,1,2,3 四种安全级别的标记。
与R1,R2,W1,W2对应的是在session key(access token)颁发时增加了4个过期时间:r1_expires_in、r2_expires_in、w1_expires_in、w2_expires_in。这4个值分别用来表示此session key调用各级别API或字段的有效期。
受安全等级限制的应用有:在线订购应用、第三方IT工具、服务商后台系统、店铺模块后台这4类应用;商家后台系统和新业务这类卖家自用型应用暂不受影响。
安全等级 |
API级别 |
正式环境测试中 |
上线运行中 |
是否可刷新 |
Refresh刷新时长 |
3级 |
R1 |
24小时 |
同订购时长 |
是 |
已上线应用与订购时长一致,正式环境测试24小时有效 |
R2 |
24小时 |
同订购时长 |
是 |
||
W1 |
24小时 |
同订购时长 |
是 |
||
W2 |
24小时 |
同订购时长 |
是 |
||
2级 |
R1 |
24小时 |
同订购时长 |
是 |
已上线应用与订购时长一致,正式环境测试24小时有效 |
R2 |
24小时 |
72小时 |
是 |
||
W1 |
24小时 |
同订购时长 |
是 |
||
W2 |
30分钟 |
30分钟 |
否 |
||
1级 |
R1 |
24小时 |
同订购时长 |
是 |
已上线应用与订购时长一致,正式环境测试24小时有效 |
R2 |
24小时 |
24小时 |
否 |
||
W1 |
24小时 |
同订购时长 |
是 |
||
W2 |
5分钟 |
5分钟 |
否 |
||
0级 |
R1 |
30分钟 |
30分钟 |
否 |
0 |
R2 |
0分钟 |
0分钟 |
否 |
||
W1 |
30分钟 |
30分钟 |
否 |
||
W2 |
0分钟 |
0分钟 |
否 |
注意:
第三方IT工具包括但不限于以下发布到服务市场应用标签(订单付费,互动应用,电商财务,图片/视频工具,快递运输应用,行业/店铺分析,商品管理,阿里妈妈营销工具,客服应用,促销管理,千牛插件,客户关系管理,ERP/进销存软件,订单管理,DMP人群营销,协同办公)
授权获得的access_token有效时长(expires_in )和标签类型(如IT工具、商家后台系统等)、状态(如正式环境、上线等)有关。
注:
1)实际api调用时,对应用授权时长做了更精确的控制,具体可参考(API安全等级);
2)像“第三方IT工具” 类应用开发上线后都是发布在 服务市场上,卖家需要订购使用,相应授权时长会和订购时长相同,如购买1个月,则取得的access_token有效时长1个月。
业务类别 |
应用标签 |
正式环境测试中 |
上线运行中 |
|
SessionKey授权时间 |
SessionKey授权时间 |
|||
移动应用 |
YunOS服务 |
24小时 |
24小时 |
|
无线手机游戏 |
4320小时 |
|||
互动应用 |
同订购关系 |
|||
电商管理 |
我是商家 |
商家后台系统 |
8760小时 |
|
商家品牌会员 |
720小时 |
|||
天猫售后服务商 |
8760小时 |
|||
我是国际商家 |
国际商家后台系统 |
8760小时 |
||
我是去啊商家 |
去啊-国内机票 |
2160小时 |
||
去啊-门票 |
||||
去啊-国际机票 |
||||
去啊-度假 |
||||
去啊-酒店 |
||||
去啊-基础 |
||||
我是服务商 |
第三方IT工具 |
同订购关系 |
||
服务商后台系统 |
||||
在线订购应用 |
||||
广告推广 |
外部合作网站 |
24小时 |
||
其他 |
反欺诈风控 |
720小时 |
||
阿里大鱼 |
2160小时 |
例如一个安全等级为2级的应用,在用户授权后颁发一个session key(access token),同时会返回4个过期时间:r1_expires_in=2160000(单位秒,下同)、r2_expires_in=259200、w1_expires_in=2160000、w2_expires_in=1800。这些授权时长的含义如下:(1)session key颁发后1800秒内,APP可以使用这个session key调用w2级别的API或字段。另外3个过期时间含义相同。(2)session key颁发后超过1800秒,APP不可以再使用这个session key调用w2级别的API或字段。另外3个过期时间含义相同。(3)对于本例来说如果R2级别的授权过期了,可以使用refresh token刷新一下R2的授权时长(仅限第三方订购类应用)。刷新后使用新返回的sessionkey(access token)又可以重新调用R2级别的API或字段。(4)对于本例来说如果w2级别的授权过期了,如上表格所示w2级别的授权是不能刷新的。所以APP需要引导用户到授权页面重新授权 。
在【开发者控制台后台-开发-我的应用-应用管理-应用设置-授权管理】 界面查看,一般非第三方IT工具应用都无法选择 “所有人都可以使用”。
1)商家后台系统默认授权个数为1个,如果商家有多个店铺需要绑定,可以进行多店铺管理,进行授权报备;
2)注:第三方IT工具包括但不限于以下发布到服务市场应用标签(订单付费,互动应用,电商财务,图片/视频工具,快递运输应用,行业/店铺分析,商品管理,阿里妈妈营销工具,客服应用,促销管理,千牛插件,客户关系管理,ERP/进销存软件,订单管理,DMP人群营销,协同办公)
redirect_uri指的是应用发起请求时,所传的回调地址参数,在用户授权后应用会跳转至redirect_uri。
callback指的是应用注册时填写的回调地址链接,或者网站接入时所验证的域名地址。
相关的规则是:
1)Server-side flow,redirect_uri是必选参数,并且要求redirect_uri与callback的。
2)Client-side flow,redirect_uri是可选参数,如果传了redirect_uri,则相应的中间参数会返回到redirect_uri,并且要求redirect_ur与callback的顶级域名一致,如果没有传redirect_uri,则不做校验,返回相应的中间参数到淘宝默认授权返回页面。
3)在不可预知错误的情况下,返回到默认错误页面。
错误信息 |
错误原因 |
request method must be get |
该请求必须用GET方法 |
request method must be post |
该请求必须用POST方法 |
client_id is empty |
client_id(即appkey)不能为空 |
response_type is empty |
response_type不能为空 |
redirect_uri is empty |
redirect_uri不能为空 |
grant type is empty |
grant type不能为空 |
authorize code is empty |
authorize code不能为空 |
unsupported response type,the response type must code or token |
response type的值必须为code或者token |
redirect_uri is invalidate |
redirect_uri校验失败,请检查你在开发者中心注册的回调地址和redirect_uri是否一致 |
the grant type unsupported |
grant type值无效 |
authorize reject |
用户拒绝授权 |
authorize code expire |
authorize code失效,请重新授权 |
authorize code xxxx invalidate,please authorize again. |
authorize code失效,请重新授权 |
client_secret is invalidate |
app secret校验失败 |
xss chars included in params, such as <, >, ', " |
请求参数中带有以下字符:<, >, ', " |
The Application already Bind with user ids:xxx |
APP已经绑定了用户xxx。请到开发者中心“授权管理”页面设置绑定的用户nick |
Can not find the client_id:xxxxx |
client_id(即appkey)不存在 |
Application need publish |
只有状态为“正式环境测试”和“上线运行中”的应用才允许授权 |
Application xxx need purchase |
必须先订购才能使用 |
app call back is invalidate |
应用的回调地址不合法 |
application callback can not match the redirect_uri |
redirect_uri和事先配置的回调地址不匹配 |
only support http or https |
回调URL只支持https或http协议 |
application in black list,access forbidden. |
app存在黑名单中 |
application session type must be common |
session key类型不正确(只支持现有的常规sessionkey和订购类型sessionkey) |
The application don't need session |
此应用不需要sessionkey,不用刷新sessionkey |
session key num is larger than xx |
有效sessionkey个数超过上限 |
userid is invalidate |
userId 不存在 |
login failure |
用户登录失败 |
login sign failure |
无线登录签名校验失败 |
taobao staff can't accredit |
淘宝小二不允许访问 |
subuser can't access |
应用不支持子账号访问 |
parent account forbid this sub account to access app. |
父账号未授权此子账号访问应用 |
parent account forbidden |
父账号未授权或授权已过期 |
refresh token is empty |
refresh token为空 |
refresh token is error:xxxx |
refresh token内容有误,解析失败 |
refresh token is invalid |
refresh token已经失效 |
refresh times limit exceed |
刷新次数超过上限,一个sessionkey一天最多可刷新60次 |
session expire |
当前会话已经过期,可能用户浏览器暂停太久已经超时 |
OAUTH SERVER ERROR:xxxxx |
系统内部错误,请重试 |
Iossdk params is lack |
缺少ios sdk协议参数 |
iossdk track_id is invalid |
ios sdk协议参数track id校验失败。建议核对一下appsecret |
iossdk params check failed |
ios sdk协议参数校验失败 |
1.Q:授权获取token时,appkey已传入,仍报:client_id is empty 错误?
A:授权另一关键参数client_secret错误,会导报该错误,请重点检查。
2.Q:淘宝子账号授权报错问题?
A:淘宝子账号授权应用,必须先用店铺主账号授权,主账号再给子账号开通应用使用权限(参考《子账号授权流程介绍》),然后才可以进行子账号授权。
可能还会出现报错:parent account forbid this sub account to access app , 这个是主账号没有给相应子账号开通 应用使用的权限,需要在子账号管理后台给相应账号开通权限,参考《子账号授权流程介绍》。
3.Q:C2B定制自研应用如何授权?
A:获取session_key 需要先通过my.authorize 授权,授权后使用云服务获取,云开发通过云函数context参数获取(context.accessToken), 云应用通过http param 获取access_token。
4.Q:每次同步淘宝用户数据都要网页进行用户授权,怎么实现自动同步?
A: 不同的接口授权有效时长不一样,过期授权无法同步信息。如果同步淘宝用户数据时要求重新授权,说明原授权已过期,必须重新授权。可以考虑提升ISV应用等级,延长授权时效,减少反复授权,参考《应用授权规则》。
5.Q:授权相关常用文档有那些?