用户授权介绍

更新时间：2024/09/25 访问次数：4785724

一、概述
二、web网站授权模式
三、客户端授权模式
四、刷新授权
五、名词解释
六、错误码排查
七、常见问题

一、概述

当开放平台的应用需要获取商家或者用户数据（商品、订单信息等），需要引导用户先使用淘宝帐号登录并授权您的应用，用户授权成功平台会返回用户授权码 Sessionkey（即access_token），之后调用接口时传入对应用户的授权码就可以获取到该用户的数据。

注意：

1）对于开发阶段sessionkey的快速获取，可以使用官方工具获取sessionkey，点击使用；通过授权工具重新授权会刷新授权有效时间。

2）授权以后的sessionkey是有有效时间的，可以通过授权Sessionkey解析查询该次授权的有效时间，更多授权工具可以使用授权常用工具。

3）文档描述的用户授权操作仅适用于web应用授权使用，如果是手机淘宝/天猫客户端小程序开发，请参考《授权场景》。

4） sessionkey是根据应用appkey与授权账号生成的，使用哪个商家的淘宝账号授权，就仅能获取该商家的数据。

以下是关于授权的具体技术实现方案，开发者可以根据需要选择合适的授权方式。

二、web网站授权模式

此流程需要您有自己的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/），创建登记您的应用，这里不再详细展开介绍，请参考《新手指南》。

第二步：拼接授权URL

拼接规则示例：

https://oauth.taobao.com/authorize?response_type=code&client_id=11111111&redirect_uri=http://www.taobao.com&state=1212&view=web

示例中的 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。

第四步：获取code

用户授权登录后，TOP会将授权码 code 返回到回调地址URL，开发者可以获取并使用该 code 换取 access_token。

1）code 有效期是30分钟，超过30分钟未使用，需要重新按授权流程获取；

2）code 只能使用一次，使用后需要重新按授权流程获取。

3）发布到服务市场的应用（如购物应用的用户），在应用上线后，通过【我的订单】-直接点击【使用】，系统会自动跳转到授权页面，因此不需要进行第二步拼接URL，只需注意获取code即可。

第五步：换取access_token

方式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 示例：
<php/*测试时，需把test参数换成自己应用对应的值*/$url = 'https://oauth.taobao.com/token';$postfields= array('grant_type'=>'authorization_code','client_id'=>'test','client_secret'=>'test','code'=>'test','redirect_uri'=>'http://www.test.com');$post_data = '';foreach($postfields as $key=>$value){$post_data .="$key=".urlencode($value)."&";}$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);//指定post数据curl_setopt($ch, CURLOPT_POST, true);//添加变量curl_setopt($ch, CURLOPT_POSTFIELDS, substr($post_data,0,-1));$output = curl_exec($ch);$httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);echo $httpStatusCode;curl_close($ch);var_dump($output);>

JAVA 示例：
import java.io.IOException;import java.util.HashMap;import java.util.Map;import com.taobao.api.internal.util.WebUtils; //引用top sdkpublic class open_oauth {public static void main(String[] args) {String url="https://oauth.taobao.com/token";Map<String,String> props=new HashMap<String,String>();props.put("grant_type","authorization_code");/*测试时，需把test参数换成自己应用对应的值*/props.put("code","test");props.put("client_id","test");props.put("client_secret","test");props.put("redirect_uri","http://www.test.com");props.put("view","web");String s="";try{s=WebUtils.doPost(url, props, 30000, 30000);System.out.println(s);}catch(IOException e){e.printStackTrace();}} }

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字段，返回结果内容示例：

{
"w2_expires_in": 0,
"taobao_user_id": "263685215",
"taobao_user_nick": "%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B752",
"w1_expires_in": 1800,
"re_expires_in": 0,
"r2_expires_in": 0,
"expires_in": 86400,
"token_type": "Bearer",
"refresh_token": "6200e1909ca29b04685c49d67f5ZZ3675347c0c6d5abccd263685215",
"access_token": "6200819d9366af1383023a19907ZZf9048e4c14fd56333b263685215",
"r1_expires_in": 1800
}

三、客户端授权模式

客户端应用授权方式，适合ISV应用没有独立的web Server，需要借助浏览器或者JS脚本访问授权服务器，或者用户手动复制页面上的sessionkey输入到客户端。一般适用于自研应用或者低频使用的场景。

第三方应用授权的流程如下所示。

第一步：创建应用

同上第一步，详情参考上文。

第二步：拼接授权url

获取授权码: 拼接以https://oauth.taobao.com/authorize开头的url 。

拼接规则样例：

https://oauth.taobao.com/authorize?response_type=token&client_id=11111111&state=1212&view=web

相关参数位置及说明，同上第二步。

第三步：引导用户登录授权

这一步同上授权方式，引导用户访问授权URL进行授权，如下。

第四步：获取access_token

此处上图页面点授权后，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;
import java.util.HashMap;
import java.util.Map;
import com.taobao.api.internal.util.WebUtils;

public class test_refresh {

public static void main(String[] args) {
String url="https://oauth.taobao.com/token";
Map<String,String> props=new HashMap<String,String>();
props.put("grant_type","refresh_token");
props.put("refresh_token","test");
props.put("client_id","test");
props.put("client_secret","test");
String s="";
try{s=WebUtils.doPost(url, props, 30000, 30000);
System.out.println(s);
}catch(IOException e){
e.printStackTrace();
}
}

以上把responseJson 转化为对象，或者直接从里面提取access_token字段以及新的刷新令牌。refresh_token返回结果内容示例：

五、名词解释

1. Access Token / Session Key

AccessToken即用户授权后颁发的SessionKey，也称为数据加密密钥或者工作密钥，当您调用淘宝开放平台涉及用户隐私数据的API接口时，需要传递TOP颁发给应用的授权信息（session_key参数），才能成功调用。

例如，调用 taobao.user.buyer.get API获取买家信息，要求ISV应用必须先得到商家用户授权，获取相关session_key，传递相关参数，才能查询到买家信息。如下图所示。

2. 安全等级

为了更加灵活地对淘宝开放平台开放的数据进行安全管控，降低用户数据泄露或者被恶意修改的风险。淘宝开放平台对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人群营销，协同办公）

3. 授权时长

授权获得的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需要引导用户到授权页面重新授权。

4. 应用授权个数

在【开发者控制台后台-开发-我的应用-应用管理-应用设置-授权管理】界面查看，一般非第三方IT工具应用都无法选择 “所有人都可以使用”。

1）商家后台系统默认授权个数为1个，如果商家有多个店铺需要绑定，可以进行多店铺管理，进行授权报备；

2）注：第三方IT工具包括但不限于以下发布到服务市场应用标签（订单付费，互动应用，电商财务，图片/视频工具，快递运输应用，行业/店铺分析，商品管理，阿里妈妈营销工具，客服应用，促销管理，千牛插件，客户关系管理，ERP/进销存软件，订单管理，DMP人群营销，协同办公）

5. redirect_uri及callback定义规则

redirect_uri指的是应用发起请求时，所传的回调地址参数，在用户授权后应用会跳转至redirect_uri。

callback指的是应用注册时填写的回调地址链接，或者网站接入时所验证的域名地址。

六、错误码排查

错误信息	错误原因
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：授权相关常用文档有那些？

A：多店铺管理、快速授权工具、安全保障&安全等级介绍及安全等级提升方法。

FAQ

怎样在淘宝帐号里授权API转链

有用(845) 我要提问