简体中文

English

简体中文

English

显示模式

访问令牌 ​

访问令牌是商家同意安装应用过程中平台授予应用的令牌，允许应用使用该访问令牌访问 REST APIs 与平台进行交互。Genstore 提供了两种获取访问令牌的方法：令牌交换和授权码授予。嵌入式应用推荐使用令牌交换，而非嵌入式应用则需通过授权码授予方式获取。

令牌交换 ​

令牌交换基于 OAuth 2.0 令牌交换规范，适用于嵌入式应用，可通过 App Bridge 获取。

实现令牌交换的步骤 ​

  1. 会话令牌请求：应用从浏览器通过嵌入式应用重定向，请求会话令牌。
  2. 验证并获取访问令牌：后端验证会话令牌并请求新的访问令牌。
  3. 使用访问令牌：Genstore 验证并返回新的访问令牌，应用使用该令牌调用 APIs。

令牌交换 API ​

请求格式如下：

bash
POST https://{shop}.genmystore.com/oauth2/token

参数说明：

  • shop：用户的商店名称。
  • clientId：应用的客户端 ID。
  • clientSecret：应用的客户端秘钥。
  • grantType：授权类型，此处为 token-exchange
  • subjectToken：会话 ID
  • requestedTokenType：请求的令牌类型，在线指定 online-access-token，默认为离线。

TIP

关于在线和离线令牌，可阅读 在线访问令牌与离线访问令牌

示例 ​

令牌交换请求：

bash
curl -X POST \
  https://{shop}.genmystore.com/oauth2/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
      "clientId": "{client_id}",
      "clientSecret": "{client_secret}",
      "grantType": "token-exchange",
      "subjectToken": "{session_token}",
      "requestedTokenType": "online-access-token"
  }'

令牌交换响应:

  • 在线令牌
bash
{
  "accessToken": "3f56c8bf63277ef253027f17",
  "scope": "write_orders,read_products",
  "expiresIn": 86399,
  "associatedUser": {
	"id": 1818181818,
	"email": "[email protected]"
  }
}
  • 离线令牌
bash
{
  "accessToken": "3f56c8bf63277ef253027f17",
  "scope": "write_orders,read_products"
}

授权码授予 ​

非嵌入式应用需使用 OAuth 2.0 的授权码授予 方式获取访问令牌，遵循 OAuth 2.0 的行业标准规范。

授权码授予过程 ​

  1. 用户访问应用，应用引导用户至授权页面。
  2. 用户同意授权后，授权中心返回授权码。
  3. 应用使用授权码请求访问令牌。
  4. Genstore 返回访问令牌，应用使用该令牌访问所需资源。

请求授权码 ​

请求格式如下：

bash
POST https://{shop}.genmystore/oauth2/authorize?clientId={client_id}&scope={scopes}&redirectUri={redirect_uri}&state={nonce}&requestedTokenType={access_mode}

参数说明：

  • shop：用户的商店名称。
  • clientId：应用程序的客户端 ID。
  • scope：授权范围
  • redirectUri：回调地址
  • state：用于应用安全校验，将在返回授权码时回传此参数
  • requestedTokenType：设置访问模式。在线指定 online-access-token，默认为离线。

TIP

关于在线和离线令牌，可阅读 在线访问令牌与离线访问令牌

通过授权码换取访问令牌 ​

请求格式如下：

bash
POST https://{shop}.genmystore.com/oauth2/token

参数说明：

  • clientId：应用程序的客户端 ID。
  • clientSecret：应用程序的客户端秘钥。
  • grantType：授权码方式，枚举值 "code"。
  • code：授权码。

示例 ​

请求：

bash
curl -X POST \
  https://{shop}.genmystore.com/oauth2/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
      "clientId": "{client_id}",
      "clientSecret": "{client_secret}",
      "grantType": "code",
      "code": "{code}",
  }'

响应

  • 在线令牌
bash
{
  "accessToken": "3f56c8bf63277ef253027f17",
  "scope": "write_orders,read_products",
  "expiresIn": 86399,
  "associatedUser": {
	"id": 1818181818,
	"email": "[email protected]"
  }
}
  • 离线令牌
bash
{
  "accessToken": "3f56c8bf63277ef253027f17",
  "scope": "write_orders,read_products"
}

在线访问令牌与离线访问令牌 ​

创建 API 访问令牌时，可以在两种访问模式之间进行选择：离线和在线，默认为离线。

在线访问令牌 ​

  • 具有在线访问模式的令牌与商店中的单个用户相关联，其中访问令牌的生命周期与用户的 Web 会话的生命周期相匹配。
  • 在线访问适用于用户通过网络与应用交互时，应用必须尊重个人用户的权限级别时的场景。
  • 应用的安全要求指定了对商店的短期访问。具有在线访问模式的令牌将在用户注销时不可使用。

离线访问令牌 ​

  • 具有离线访问模式的令牌用于长期访问商店，其中不涉及任何用户交互。离线访问模式非常适合响应 Webhook 的后台工作，或后台作业中的维护工作。
  • 多次授权应用离线访问时，每次都会返回相同的访问令牌。获得商店的离线访问权限后，仅在卸载应用后或需要其他访问范围时才需要重新授权应用。
  • 使用离线访问模式创建的访问令牌是永久性的。仅当从商店卸载应用程序时，它们才会被撤销。