简体中文

English

简体中文

English

访问令牌 ​

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

令牌交换 ​

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

实现令牌交换的步骤 ​

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

令牌交换 API ​

请求格式如下：

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

参数说明：

  • 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": "junwei@example.com"
  }
}
  • 离线令牌
bash
{
  "accessToken": "3f56c8bf63277ef253027f17",
  "scope": "write_orders,read_products"
}

授权码授予 ​

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

授权码授予过程 ​

  1. 用户在 Genstore 平台访问应用，平台引导用户至应用配置 URL。
  2. 如未安装授权，应用需引导用户至授权页面。
  3. 用户同意授权后，授权中心返回授权码。
  4. 应用使用授权码请求访问令牌。
  5. Genstore 返回访问令牌，应用使用该令牌访问所需资源。

跳转应用 URL ​

当用户从 Genstore 访问你的应用时，平台会将用户跳转至应用的配置 URL，并在请求中附带 shopId、shop、timestamp 和 hmac 参数。你需要验证 hmac 以确保请求的真实性。

请求格式如下：

bash
https://{APP URL}?shop={shop}&shopId={shopId}&timestamp={timestamp}&hmac={hmac}

参数说明：

  • APP URL：应用配置的 URL。
  • shopId：店铺 ID。
  • shop：商家店铺域名。
  • timestamp：时间戳。
  • hmac：请求签名。

请求授权码 ​

请求格式如下：

bash
https://{shop}.genmystore.com/admin/oauth2/authorize?clientId={client_id}&scope={scopes}&redirectUrl={redirectUrl}&state={nonce}&grantType={code}

参数说明：

  • shop：商家店铺域名。
  • clientId：应用程序的客户端 ID。
  • scope：授权范围。
  • redirectUrl：回调地址，需要与应用配置的回调地址保持一致。
  • state：用于应用安全校验，将在返回授权码时回传此参数。
  • grantType：授权类型，授权码授予为 code。

重定向返回授权码 ​

应用通过重定向 code 参数获取授权码，重定向URL如下：

bash
https://{redirectUrl}?shop={shop}&shopId={shopId}&state={state}&timestamp={timestamp}&code={code}&hmac={hmac}

参数说明：

  • redirectUrl: 应用回调重定向地址。
  • shop：店铺域名。
  • shopId：店铺 ID。
  • state：用于应用安全校验，将在返回授权码时回传此参数。
  • timestamp：时间戳。
  • code：授权码。
  • hmac：请求签名。

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

请求格式如下：

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",
  "shopId": 988716383,
  "shopDomain":"xxx.genmystore.com"
}

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

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

在线访问令牌 ​

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

离线访问令牌 ​

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