授权访问

授权流程说明

卡游售卖机开放平台 OAuth2.0授权让 卡游售卖机开放平台 用户可以使用 卡游售卖机开放平台 用户身份安全访问第三方应用或者网站，第三方应用或者网站可以获取到用户的接口调用凭证（accessToken），通过accessToken可以进行 卡游售卖机开放平台 卡游售卖机开放平台 授权接口调用，从而可实现获取 卡游售卖机开放平台 用户基本开放信息等功能。 卡游售卖机开放平台 OAuth2.0授权目前支持authorization_code模式和client_credentials模式，适用于拥有服务端的第三方应用授权。

client_credentials模式

该模式的流程如下：

1. 向 卡游售卖机开放平台 申请账号：clientId、clientSecret和appid；
2. 通过 grantType 参数加上clientId、clientSecret等，通过API换取accessToken;
3. 通过accessToken进行接口调用，获取业务数据等信息。

第一步：账号申请

请联系 卡游售卖机开放平台 相关技术或者商务人员，申请账号：clientId、clientSecret和appid。

第二步： 通过code获取accessToken

通过 grantType 参数加上clientId、clientSecret获取accessToken

• 接口

GET /api/oauth/token?grantType=client_credentials&appid=APPID

• 请求参数

  • Header:

  参数名称	参数值	是否必填	示例	备注
  Authorization	Basic dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ=	是	Basic dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ=	base64_encode(clientId:clientSecret)

  • Query:

  参数名称	是否必填	示例	备注
  grantType	是	client_credentials	授权码则传authorization_code
  appid	是	10200	第三方应用id

• 返回数据

  名称	类型	是否必须	备注
  code	number	是	返回码
  msg	String	是	返回信息
  timestamp	number	是	时间戳
  data	object
  accessToken	String
  refreshToken	String
  expireIn	number		有效时长

• 返回说明

  • 正确的返回：

      {
          "code": 0,
          "msg": "success",
          "data": {
              "accessToken": "0b05dd7f9bd241f19194b7bfd5518b3b",
              "refreshToken": "0df3b48db66a4c8082398838487f145b",
              "expireIn": 7200
          },
          "timestamp": 1607942001
      }
  

  • 错误的返回：

      {
          "code": 500,
          "msg": "client info is invalid!",
          "timestamp": 1608006362
      }
  

• 刷新accessToken有效期 accessToken是调用授权接口的调用凭证，由于accessToken有效期（目前为2个小时）较短，当accessToken超时后，可以使用refreshToken进行刷新，accessToken刷新结果有两种：

如果accessToken已超时，那么进行refreshToken会获取一个新的accessToken以及新的refreshToken，新的超时时间。 refreshToken拥有较长的有效期(30天)， 当refreshToken失效后，需要用户重新授权通过code获取AccessToken。

• 请求方法 通过refreshToken后，请求一下接口进行refreshToken:
• 接口

GET /api/oauth/refresh?grantType=refresh_token&refreshToken=REFRESH_TOKEN

• 请求参数

  • Header:

  参数名称	参数值	是否必填	示例	备注
  Authorization	Basic dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ=	是	Basic dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ=	base64_encode(clientId:clientSecret)

  • Query:

  参数名称	是否必填	示例	备注
  grantType	是	refresh_token	授权模式使用refresh_token
  refreshToken	是	54be978ff01f44fa88d880f44170b2dd	刷新码

• 返回数据

  名称	类型	是否必须	备注
  code	number	是	返回码
  msg	String	是	返回信息
  timestamp	number	是	时间戳
  data	object
  accessToken	String
  refreshToken	String
  expireIn	number		有效时长

• 返回说明

  • 正确的返回：

      {
          "code": 0,
          "msg": "success",
          "data": {
              "accessToken": "0b05dd7f9bd241f19194b7bfd5518b3b",
              "refreshToken": "0df3b48db66a4c8082398838487f145b",
              "expireIn": 7200
          },
          "timestamp": 1607942001
      }
  

  • 错误的返回：

      {
          "code": 500,
          "msg": "client info is invalid!",
          "timestamp": 1608006362
      }
  

  • 注意：

    1. clientSecret是应用接口使用的秘钥，泄露后将可能导致应用数据泄露等高风险后果；存储在客户端极有可能被恶意窃取；

    2. accessToken为用户授权第三方应用发起接口调用的凭证（相当于用户态），存储在客户端可能出现恶意获取accessToken后导致用户数据泄露风险同上。

    3. refreshToken为用户授权第三方应用的长效凭证，仅用于刷新accessToken，但泄露后相当于accessToken泄露，风险同上。

第三步：通过accessToken调用接口

获取accessToken后进行接口调用，前提：

1. accessToken有效且未超时
2. 卡游售卖机开放平台 用户已授权第三方应用访问响应接口资源。

• 调用获取用户基础信息接口
• 接口

GET /openapi/platform/user/baseinfo

• 请求参数

  • Header:

  参数名称	参数值	是否必填	示例	备注
  Authorization	Bearer 12f7764bd76e4350bd87772390444d7c	是	Bearer 12f7764bd76e4350bd87772390444d7c	Bearer accessToken

• 返回数据

  名称	类型	是否必须	备注
  code	number	是	返回码
  msg	String	是	返回信息
  timestamp	number	是	时间戳
  data	object
  id	number		用户id
  mobile	String		手机号
  nickname	String		昵称

• 返回说明

  • 正确的返回：

      {
          "code": 0,
          "msg": "success",
          "data": {
                  "id": 100001,
                  "mobile": "b30607fcb81824963fa77ca577fcabaa",
                  "nickname": "182****9281"
          },
          "timestamp": 1606450537
      }
  

  • 错误的返回：

      {
          "code": 500,
          "msg": "token is timeout. please retry.",
          "timestamp": 1608008002
      }
  

authorization_code模式

该模式的流程如下：

1. 卡游售卖机开放平台 用户请求访问第三方应用， 如果用户尚未授权则弹出是否允许第三方应用获取用户信息；
2. 卡游售卖机开放平台 用户同意授权， 卡游售卖机开放平台 则会重定向到第三方网站，并且带上授权临时票据code参数（code有效时长5分钟）；
3. 通过code参数加上clientId、clientSecret等，通过API换取accessToken;
4. 通过accessToken进行接口调用，获取用户基本信息等信息。

• 获取accessToken时序图：

第一步：请求code

当 卡游售卖机开放平台 用户同意授权访问第三方应用，则 卡游售卖机开放平台 授权平台跳转到第三方应用地址，同时带上授权临时票据(code)，应用地址域名需要与提交审核时填写的域名一致。

第二步： 通过code获取accessToken

通过code获取accessToken

• 接口

GET /api/auth/oauth/token?grantType=authorization_code&code=CODE&appid=APPID

• 请求参数

  • Header:

  参数名称	参数值	是否必填	示例	备注
  Authorization	Basic dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ=	是	Basic dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ=	base64_encode(clientId:clientSecret)

  • Query:

  参数名称	是否必填	示例	备注
  grantType	是	authorization_code	授权码则传authorization_code
  code	是	54be978ff01f44fa88d880f44170b2dd	授权码模式code必须传
  appid	是	10200	第三方应用id

• 返回数据

  名称	类型	是否必须	备注
  code	number	是	返回码
  msg	String	是	返回信息
  timestamp	number	是	时间戳
  data	object
  accessToken	String
  refreshToken	String
  expireIn	number		有效时长

• 返回说明

  • 正确的返回：

      {
          "code": 0,
          "msg": "success",
          "data": {
              "accessToken": "0b05dd7f9bd241f19194b7bfd5518b3b",
              "refreshToken": "0df3b48db66a4c8082398838487f145b",
              "expireIn": 7200
          },
          "timestamp": 1607942001
      }
  

  • 错误的返回：

      {
          "code": 500,
          "msg": "client info is invalid!",
          "timestamp": 1608006362
      }
  

• 刷新accessToken有效期 accessToken是调用授权接口的调用凭证，由于accessToken有效期（目前为2个小时）较短，当accessToken超时后，可以使用refreshToken进行刷新，accessToken刷新结果有两种：

如果accessToken已超时，那么进行refreshToken会获取一个新的accessToken以及新的refreshToken，新的超时时间。 refreshToken拥有较长的有效期(30天)， 当refreshToken失效后，需要用户重新授权通过code获取AccessToken。

• 请求方法 通过refreshToken后，请求一下接口进行refreshToken:
• 接口

GET /api/auth/oauth/refresh?grantType=refresh_token&refreshToken=REFRESH_TOKEN

• 请求参数

  • Header:

  参数名称	参数值	是否必填	示例	备注
  Authorization	Basic dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ=	是	Basic dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ=	base64_encode(clientId:clientSecret)

  • Query:

  参数名称	是否必填	示例	备注
  grantType	是	refresh_token	授权模式使用refresh_token
  refreshToken	是	54be978ff01f44fa88d880f44170b2dd	刷新码

• 返回数据

  名称	类型	是否必须	备注
  code	number	是	返回码
  msg	String	是	返回信息
  timestamp	number	是	时间戳
  data	object
  accessToken	String
  refreshToken	String
  expireIn	number		有效时长

• 返回说明

  • 正确的返回：

      {
          "code": 0,
          "msg": "success",
          "data": {
              "accessToken": "0b05dd7f9bd241f19194b7bfd5518b3b",
              "refreshToken": "0df3b48db66a4c8082398838487f145b",
              "expireIn": 7200
          },
          "timestamp": 1607942001
      }
  

  • 错误的返回：

      {
          "code": 500,
          "msg": "client info is invalid!",
          "timestamp": 1608006362
      }
  

  • 注意：

    1. clientSecret是应用接口使用的秘钥，泄露后将可能导致应用数据泄露等高风险后果；存储在客户端极有可能被恶意窃取；

    2. accessToken为用户授权第三方应用发起接口调用的凭证（相当于用户态），存储在客户端可能出现恶意获取accessToken后导致用户数据泄露风险同上。

    3. refreshToken为用户授权第三方应用的长效凭证，仅用于刷新accessToken，但泄露后相当于accessToken泄露，风险同上。

第三步：通过accessToken调用接口

获取accessToken后进行接口调用，前提：

1. accessToken有效且未超时
2. 卡游售卖机开放平台 用户已授权第三方应用访问响应接口资源。

• 调用获取用户基础信息接口
• 接口

GET /openapi/platform/user/baseinfo

• 请求参数

  • Header:

  参数名称	参数值	是否必填	示例	备注
  Authorization	Bearer 12f7764bd76e4350bd87772390444d7c	是	Bearer 12f7764bd76e4350bd87772390444d7c	Bearer accessToken

• 返回数据

  名称	类型	是否必须	备注
  code	number	是	返回码
  msg	String	是	返回信息
  timestamp	number	是	时间戳
  data	object
  id	number		用户id
  mobile	String		手机号
  nickname	String		昵称

• 返回说明

  • 正确的返回：

      {
          "code": 0,
          "msg": "success",
          "data": {
                  "id": 100001,
                  "mobile": "b30607fcb81824963fa77ca577fcabaa",
                  "nickname": "182****9281"
          },
          "timestamp": 1606450537
      }
  

  • 错误的返回：

      {
          "code": 500,
          "msg": "token is timeout. please retry.",
          "timestamp": 1608008002
      }
  

• 调用获取用户信息接口

• 接口

GET /openapi/platform/user/detail

• 请求参数

  • Header:

  参数名称	参数值	是否必填	示例	备注
  Authorization	Bearer 12f7764bd76e4350bd87772390444d7c	是	Bearer 12f7764bd76e4350bd87772390444d7c	Bearer accessToken

• 返回数据

  名称	类型	是否必须	备注
  code	number	是	返回码
  msg	String	是	返回信息
  timestamp	number	是	时间戳
  data	object
  id	number		用户id
  mobile	String		手机号
  nickname	String		昵称
  realName	String		真实姓名
  idCard	String		身份证
  gender	number		性别，1=男，2=女
  level	Boolean		是否实名认证0是未实名1是实名2是实人实名

• 返回说明

  • 正确的返回：

      {
          "code": 0,
          "msg": "success",
          "data": {
              "id": 100001,
              "mobile": "b30607fcb81824963fa77ca577fcabaa",
              "nickname": "182****9281",
              "realName": "0d909397a47de2aad09f7e189f035720",
              "idCard": "b8256c661944a5c2e0dbcd70ea045da7244ee3ba243f4eaf4b4fe22c7615fd2e",
              "gender": 1,
              "level": 2
          },
          "timestamp": 1606450537
      }
  

  • 错误的返回：

      {
          "code": 500,
          "msg": "token is timeout. please retry.",
          "timestamp": 1608008002
      }