用户授权介绍
登录授权
如果您的应用和淘宝开放平台对接时需要获取用户隐私数据（如商品、订单等），为保证用户数据的安全与隐私，您的应用需要取得用户的授权，即获取访问用户数据的授权令牌 Access Token （也叫SessionKey）。这种情况下，您的应用需要引导用户完成使用淘宝帐号“登录授权”的流程。该流程采用国际通用的OAuth2.0标准协议作为用户身份验证与授权协议，支持网站、手机客户端、桌面客户端。
目前淘宝OAuth2.0服务支持采用两种方式获取Access Token（授权令牌），即 Server-side flow 和 Client-side flow ，详见如下说明。
特别注意
此文档描述的授权页面仅适用于PC端，如果您的页面是在手机淘宝/天猫客户端中被访问，请参考这里。如果您的页面是在H5手机浏览器中被访问，请参考这里。
如果是要快速生成一个授权sessionkey， 可以直接通过 授权工具 生成，登陆需要授权的账号，输入需要授权的appkey。
一、Server-side flow
此流程要求ISV应用有Web Server应用，能够保存应用本身的密钥以及状态，可以通过https直接访问淘宝的授权服务器。
1、请求入口地址
1）获取授权码（code）
正式环境：https://oauth.taobao.com/authorize
沙箱环境：http://oauth.daily.taobao.net/authorize
备注：访问沙箱环境需要安装chrome插件，查看安装步骤
2）获取访问令牌（access_token）
正式环境：https://oauth.taobao.com/token
沙箱环境：https://gw.api.tbsandbox.com/router/rest
2、授权操作步骤
此处以正式环境获取acccess_token为例说明，如果是沙箱环境测试，需将请求入口地址等相关数据换成沙箱对应入口地址，操作流程则同正式环境一致。
实际进行授权操作时，测试的数据 client_id、client_secret、redirect_uri 均需要根据自己创建的应用实际数据给予替换，不能拿示例中给出的值直接进行测试，以免影响实际测试效果。下图为Server-side flow 授权方式流程图，以下按流程图逐步说明。
授权步骤
1）拼接授权url
拼接用户授权需访问url ，示例及参数说明如下：
https://oauth.taobao.com/authorize?response_type=code&client_id=23075594&redirect_uri=http://www.oauth.net/2/&state=1212&view=web
参数说明
名称 是否必选 参数值 参数释义
client_id 必选 等同于appkey，创建应用时获得。
response_type 必选 code 授权类型 ，值为code。
redirect_uri 必选 可填写应用注册时回调地址域名。 redirect_uri指的是应用发起请求时，所传的回调地址参数，在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致 。
state 可选 可自定义，如1212等； 维持应用的状态，传入值与返回值保持一致。
view 可选 web,可选web、tmall或wap其中一种，默认为web。 Web对应PC端（淘宝logo）浏览器页面样式；Tmall对应天猫的浏览器页面样式；Wap对应无线端的浏览器页面样式。
2）引导用户登录授权
引导用户通过浏览器访问以上授权url，将弹出如下登录页面。用户输入账号、密码点“登录”按钮，即可进入授权页面。
授权
3）获取code
上图页面，若用户点“授权”按钮后，TOP会将授权码code 返回到了回调地址上，应用可以获取并使用该code去换取access_token；
若用户未点授权而是点了“取消”按钮，则返回如下结果，其中error为错误码，error_description为错误描述。分别如下图所示：错误
说明：
可发布服务市场（fuwu.taobao.com）的应用，在应用上线后，如购买应用的用户，通过"我的服务–立即使用”访问（下图)，系统会自动跳到授权页面（因此这种方式访问应用的，不需要拼接url），只需注意获取code即可。同时返回code时，还会返回通过state传递订购服务相关的信息，类似：
state=versionNo:1;itemCode:xxxxx （versionNo 为应用版本号、itemCode为应用收费代码）
4）换取access_token
方式1（推荐）：
通过taobao.top.auth.token.create api接口获取access_token（授权令牌）。api服务地址参考http://open.taobao.com/docs/doc.htm?docType=1&articleId=101617&treeId=1
方式2：
利用linux 的curl 命令 获取access_token（授权令牌），如下；对于应用程序，可以参考文档示例这里的示例代码。
curl -i -d "code=OxlukWofLrB1Db1M6aJGF8x2332458&grant_type=authorization_code&client_id=23075594&
client_secret=69a1469a1469a1469a14a9bf269a14&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对应无线端的浏览器页面样式。
换取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
}
换取access_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
sub_taobao_user_id string 2343535 淘宝子账号对应id
sub_taobao_user_nick string 测试账号test:123 淘宝子账号
注意：应用回调地址需要在控制台中维护在应用基本信息中
二、Client-side flow
客户端应用授权方式，适合ISV没有独立的web Server，但是能够借助浏览器或者JS脚本访问授权服务器的应用。
1、请求入口地址
正式环境：https://oauth.taobao.com/authorize
沙箱环境：https://oauth.tbsandbox.com/authorize
2、授权操作步骤
以正式环境获取acccess_token为例说明，如果是沙箱环境请使用沙箱数据。
同时在授权过程中client_id等参数需要根据自己创建应用的实际数据给予替换，否则无法完成授权。
下图为Client-side flow 授权方式流程图，以下按流程图逐步详细说明cs flow
1）拼接授权url
https://oauth.taobao.com/authorize?response_type=token&client_id=23075594&state=1212&view=web
参数说明
名称 是否必选 参数值 参数释义
client_id 必选 等同于appkey，创建应用时获得。
response_type 必选 token 授权类型 ，值为token。
state 可选 可自定义，如1212等； 维持应用的状态，传入值与返回值保持一致。
view 可选 web,可选web、tmall或wap其中一种，默认为web。 Web对应PC端（淘宝logo）浏览器页面样式；Tmall对应天猫的浏览器页面样式；Wap对应无线端的浏览器页面样式。
2）导用户登录授权
这一步同Server-side flow授权方式，引导用户访问授权url 进行授权，如下。
3）获取access_token
此处上图页面点授权后，TOP会直接将access_token 返回到淘宝默认页面（和 Server-side flow 先返回code 再换access_token方式不同）此时可使用JS脚本（if(window.location.hash!=""){alert(window.location.hash)}）可以获取回调页面#后面的字段，从而获取到访问令牌。
返回参数示例：
https://oauth.taobao.com/oauth2?view=web#access_token=6101227f5e8c230696ac93a77b3de7daacb154c6ad98106263664221&token_type=Bearer&expires_in=86400&refresh_token=6100627e3f9202c0960a6ab5bfd704939c91635892c70dd263664221&re_expires_in=86400&r1_expires_in=86400&r2_expires_in=86400&taobao_user_id=263664221&taobao_user_nick=%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B717&w1_expires_in=86400&w2_expires_in=86400&state=1212&top_sign=3429C556FCD3F3FC52547DD31021592F
注：
此处参数返回除 top_sign 外，同Server-side flow授权返回参数相同，这里不再详细描述，具体可参考 Server-side flow 里面的说明。
top_sign 是系统生成签名参数，使用 Client-side flow 方式授权需要对该参数进行一致性验证。
4） 验证授权签名
即验证返回参数和 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_typeBearer
expires_in86400refresh_token6100627e3f9202c0960a6ab5bfd704939c91635892c70dd263664221re_expires_in86400r1_expires_in86400
r2expires_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 一致。
退出登录
退出流程目前只支持web访问，起到的作用是清除taobao.com的cookie，并不是取消用户的授权。在WAP上访问无效。
一、请求入口地址
1、正式环境：https://oauth.taobao.com/logoff
2、沙箱环境：https://oauth.tbsandbox.com/logoff
二、退出操作步骤
拼接退出url（如 https://oauth.taobao.com/logoff?client_id=12304977&view=web）并访问即可，退出后跳转到淘宝首页 。
刷新授权
注意：目前只有订购类应用可以刷新授权时间， 其他的固定授权时长的应用类型，只能让用户重新登陆授权生成新sessionkey，延长授权时间。
通过授权获取的refresh_token（前置条件：re_expires_in>0），可用来刷新access token 的r2时长。
由于r1 或w1 通常同订购时长一致，一般不需刷新，w2必须通过重新授权给予延长，故refresh_token 一般仅用于r2 有效时长的延长。
操作方法类似获取access token ，仅请求参数有区别，说明如下：
换取access_token请求参数说明
名称 是否必选 参数值 参数释义
client_id 必选 等同于AppKey，创建应用时获得。
client_secret 必选 等同于AppSecret，创建应用时获得。
grant_type 必选 refresh_token 授权类型 ，值为refresh_token
state 可选 可自定义，如1212等；维持应用的状态，传入值与返回值保持一致。
view 可选 可选web、tmall或wap其中一种，Web对应PC端（淘宝logo）浏览器页面样式；Tmall对应天猫的浏览器页面样式；Wap对应无线端的浏览器页面样式。
相关说明
一、授权时长说明
授权获得的 access_token 有效时长（expires_in ）和标签类型（如IT工具、商家后台系统等）、状态（如正式环境、上线等）相关如下。
注：实际api 调用时，对应用授权时长做了更精确的控制，具体可参考（二、安全等级说明）；另像“第三方IT工具”类应用开发上线后都是发布在 fuwu.taobao.com上，卖家需要订购使用，相应授权时长会和订购时长相同，如购买1个月，则取得的access_token有效时长1个月。
标签名称 正式环境测试 上线运行中 备注
第三方IT工具 24小时 同订购时长 申请参考这里
商家后台系统 24小时 固定时长1年 申请参考这里
服务商后台系统 24小时 同订购时长 申请参考这里
新业务 24小时 固定时长1个月 不开放
二、安全等级说明
为了更加灵活的对淘宝开放平台开放的数据进行安全管控， 降低用户数据泄露或者被恶意修改的风险，推出了安全等级的概念。
淘宝开放平台对API（或者API字段）及 应用分别打了r1、r2、w1、w2 和 0,1,2,3四种安全级别的标记。与 r1、r2、w1、w2对应的是在access token（session key）颁发时增加了4个过期时间：r1_expires_in、r2_expires_in、w1_expires_in、w2_expires_in。这4个值分别用来表示此access token 调用各级别API（或字段）的有效期,如下:(受安全等级限制的应用有：第三方IT工具、服务商后台系统、店铺模块后台这3类应用；商家后台系统和新业务这类卖家自用型应用暂不受影响。)
安全等级 API级别 正式环境测试 上线运行中 是否可刷新 Refresh刷新时长
3级 R1 24小时 同订购时长 是 已上线应用与订购时长一致，正式环境测试24小时有效
3级 R2 24小时 同订购时长 是 已上线应用与订购时长一致，正式环境测试24小时有效
3级 W1 24小时 同订购时长 是 已上线应用与订购时长一致，正式环境测试24小时有效
3级 W2 24小时 同订购时长 是 已上线应用与订购时长一致，正式环境测试24小时有效
2级 R1 24小时 同订购时长 是 已上线应用与订购时长一致，正式环境测试24小时有效
2级 R2 24小时 72小时 是 已上线应用与订购时长一致，正式环境测试24小时有效
2级 W1 24小时 同订购时长 是 已上线应用与订购时长一致，正式环境测试24小时有效
2级 W2 30分钟 30分钟 否
1级 R1 24小时 同订购时长 是 已上线应用与订购时长一致，正式环境测试24小时有效
1级 R2 24小时 24小时 否
1级 W1 24小时 同订购时长 是 已上线应用与订购时长一致，正式环境测试24小时有效
1级 W2 5分钟 5分钟 否
0级 R1 30分钟 30分钟 否
0级 R2 0分钟 0分钟 否
0级 W1 30分钟 30分钟 否
0级 W2 0分钟 0分钟 否
示例代码
一、获取access_token示例
示例代码均基于sdk实现，sdk下载及使用参考 说明。
1、JAVA 示例
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import com.taobao.api.internal.util.WebUtils; //引用top sdk
public 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();}
} }
2、PHP 示例
3、.NET 示例
namespace Oauth2._0
{
class Program
{
static void Main(string[] args)
{
WebUtils webUtils = new WebUtils();
IDictionary<string, string> pout = new Dictionary<string, string>();
pout.Add(“grant_type”, “authorization_code”);
pout.Add(“client_id”, “test”);
pout.Add(“client_secret”, “test”);
pout.Add(“code”, “test”);
pout.Add(“redirect_uri”, “http://www.test.com”);
string output = webUtils.DoPost(“https://oauth.taobao.com/token”, pout);
Console.Write(output);
Console.ReadLine();
}
}
}
二、refresh_token刷新示例
方式1（推荐）：
通过taobao.top.auth.token.refresh api接口刷新token。每次刷新后原来refresh_token作废，都要更新成最新返回的refresh_token用于下次刷新。api服务地址参考http://open.taobao.com/docs/doc.htm?docType=1&articleId=101617&treeId=1
方式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返回结果内容示例
{
“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
}
常见问题
1、授权获取token时，appkey是已传入，仍报：client_id is empty 错误？
授权另一关键参数client_secret错误，会导报该错误，重点检查
2、是否一定需要沙箱先进行授权测试？
并不做这样要求，可以是“先沙箱测试授权，再正式环境”的方式；也可以直接“正式环境测试授权”的方式
3、授权相关常用文档有那些？
多店铺管理：查看
快速授权工具：查看
提高安全等级办法：查看
安全等级详细说明：查看
4、授权更多问题及错误码参考：查看
