开放应用，是指通过友好速搭审核，进入应用市场的应用。

要开发开放应用，开发者需要拥有合作伙伴帐号，并通过企业资质认证。

开放应用的 OAuth2 授权过程，参照：Authorization Code。

授权流程示例：

在友好速搭的 OAuth2 实现中，上图的组成部分对应如下：

• Client：开放应用
• Resource Owner：友好速搭的用户
• Authorization Server：地址是https://apps.youhaosuda.com/oauth2/
• Resource Server：地址是https://api.youhaosuda.com/v1/...

下面介绍友好速搭 OAuth2 授权过程：

• 第一步：获取应用凭证
• 第二步：用户安装应用
• 第三步：请求授权
• 第四步：确认安装
• 第五步：使用开放 API
• 友好速搭 API 权限
• 跳转请求安全验证

第一步：获取应用凭证

在应用创建后，就能获取对应的 App Key 和 App Secret，要做好保密工作，防止泄露这两个值，尤其是 App Secret。

第二步：用户安装应用

在用户在应用市场，选择了应用，点击安装时，友好速搭会向应用发起请求，请求的URL，是应用在创建时填写的 callback 网址，完整的请求 URL 示例如下： http://example.org/some/redirect/uri?shop_key={shop_key}&account_id={account_id}&time_stamp={time_stamp}&hmac={hmac} 网址中参数包括：

• shop_key：店铺唯一标识
• account_id：用户的唯一标志
• time_stamp：时间戳
• hmac：安全验证码，参见跳转请求安全验证

第三步：请求授权

应用在验证来自友好速搭的请求后，需再次跳转到友好速搭，来获取用户授权，跳转网址示例： https://apps.youhaosuda.com/oauth2/authorize?response_type={response_type}&client_id={client_id}&shop_key={shop_key}&scope={scope}&state={state}&redirect_uri={redirect_uri} 网址中参数包括如下：

• response_type：必须，值必须为code
• client_id：必须，值为应用的 App Key
• shop_key：必须，上一步网址中的shop_key
• scope：必须，多个 API 权限以,间隔
• state：可选，若包含此参数，则在用户授权后跳转，将这个参数返回
• redirect_uri：可选，若不带此参数，将使用应用创建时填写的回调网址

第四步：确认安装

当用户确认授权后，友好速搭将会再次将用户跳转到应用，跳转网址如下： https://example.org/some/redirect/uri?code={code}&shop_key={shop_key}&account_id={account_id}&time_stamp={time_stamp}&hmac={hmac} 网址中参数包括：

• code：授权码（Authorization Code）
• shop_key：上一步网址中的shop_key
• account_id：用户的唯一标志
• time_stamp：时间戳
• hmac：安全验证码，参见跳转请求安全验证

应用在收到授权码后，可以发起POST请求，来获取 Access Token：

POST https://apps.youhaosuda.com/oauth2/token

POST请求中，需包含如下 form-data （application/x-www-form-urlencoded）参数：

• grant_type：必须，值必须为authorization_code
• code：必须，值为上述的授权码
• client_id：必须，值为应用的 App Key
• redirect_uri：必须，且必须是请求授权中使用的参数：redirect_uri

若请求合法，服务器将返回应用操作 API 的 access token：

{
  "token": "f85632530bf277ec9ac6f649fc327f17"
}

这个 access token 不会过期，应用需要持久存储这个值，并确保不会泄露。

第五步：使用开放 API

应用在获取API的 access token 后，就可以访问权限范围内的 API。在访问 API 的请求头中，加入X-API-ACCESS-TOKEN字段，值为上步返回的 access token。

友好速搭 API 权限

对部分 API 有权限限制，如下表：

权限名称	资源对象
read_basic,write_basic	Shop, Metafield, Account, Country, Province, City, District
read_content,write_content	Page, Redirect, Webhook
read_themes,write_themes	Theme, Asset
read_products,write_products	Product, ProductVariant, ProductImage
read_customers,write_customers	Customer, CustomerAddress
read_orders,write_orders	Order, Payment, PaymentMehod, Shipment, ShipmentSupplier
read_script_tags,write_script_tags	ScriptTag

当需要操作上表资源对象时，需要在请求授权的scope参数中，包含指定权限。 未在上表列出的资源对象，无权限限制。

当应用需要更新已安装应用的scope时，只需重新跳转到请求授权来通知已安装应用，再次确认授权来更新scope值。

应用删除通知

用户在店铺后台删除应用时，友好速搭会使用 webhook 方式来通知第三方应用，通知地址为创建应用时填写的 callback 地址，完整的请求 URL 示例如下： http://example.org/some/redirect/uri?event=delete&shop_key={shop_key}&time_stamp={time_stamp}&hmac={hmac} 网址中参数包括：

• event：通知事件类型，当前操作为delete
• shop_key：应用授权中的shop_key
• time_stamp：时间戳
• hmac：安全验证码，参见跳转请求安全验证

更新 App Secret

应用可以在合作伙伴后台，应用详细页面重新生成 App Secret，此时友好速搭将分发一个新的 App Secret给应用使用，此时所有的跳转 hmac的签名将使用新的 Secret 进行加密，应用需及时将旧的 Secret 进行替换，以防用户在使用过程中出现问题。

更新 Access Token

应用可以在合作伙伴后台，应用详细页面生成 Refresh Token 来手动触发更新店铺访问 API 的 Access Token。Refresh Token的时效为1小时。 应用生成 Refresh Token，可以发起POST请求，来获取来刷新访问 API的 Access Token：

POST https://apps.youhaosuda.com/oauth2/refresh_token

POST请求中，需包含如下 form-data （application/x-www-form-urlencoded）参数：

• refresh_token：必须，生成的 Refresh Token
• client_id：必须，值为应用的 App Key
• shop_key：需要刷新 access token 的店铺唯一标识

若请求合法，服务器将返回新的访问 API 的 access token：

{
  "token": "f85632530bf277ec9ac6f649fc327f17"
}

跳转请求安全验证

从友好速搭跳转到应用的请求，在参数中都包含hmac，应用可以验证这个字段，来确认请求是否来源自友好速搭。

以下示例如果计算hmac，在不同场景的跳转中，所带参数会有区别，除了hmac以外的参数，都需参与计算。

例如友好速搭返回授权码的请求参数如下：

"shop_key=a94a110d86d2452eb3e2af4cfb8a3828&code=a84a110d86d2452eb3e2af4cfb8a3828&account_id=1&time_stamp=2013-08-27T13:58:35Z&hmac=a2a3e2dcd8a82fd9070707d4d921ac4cdc842935bf57bc38c488300ef3960726"

将请求中的所有参数，转换成如下的字典：

{  
  "shop_key": "a94a110d86d2452eb3e2af4cfb8a3828",  
  "code": "a84a110d86d2452eb3e2af4cfb8a3828",  
  "account_id": "1",
  "time_stamp": "2013-08-27T13:58:35Z",    
  "hmac": "a2a3e2dcd8a82fd9070707d4d921ac4cdc842935bf57bc38c488300ef3960726"
}

将上面字典结构中，hmac字段剔除，得到下面的结构：

{ 
  "shop_key": "a94a110d86d2452eb3e2af4cfb8a3828",  
  "code": "a84a110d86d2452eb3e2af4cfb8a3828",  
  "account_id": "1",
  "time_stamp": "2013-08-27T13:58:35Z"
}

将上面的字典，按照键值正序排列，组成字符串：

"account_id=1&code=a84a110d86d2452eb3e2af4cfb8a3828&shop_key=a94a110d86d2452eb3e2af4cfb8a3828&time_stamp=2013-08-27T13:58:35Z"

最后，将上面的字符串，应用密钥，通过 HMAC-SHA256 加密，Ruby 代码示例如下：

digest = OpenSSL::Digest.new('sha256')
# 仅作示例，应使用应用的Secret
secret = "hush"
message = "account_id=1&code=a84a110d86d2452eb3e2af4cfb8a3828&shop_key=a94a110d86d2452eb3e2af4cfb8a3828&time_stamp=2013-08-27T13:58:35Z"
digest = OpenSSL::HMAC.hexdigest(digest, secret, message)
# 判断结果是否相同
digest == "a2a3e2dcd8a82fd9070707d4d921ac4cdc842935bf57bc38c488300ef3960726"

计算得出的结果，如和请求参数中的hmac相同，则说明请求确实来自友好速搭。

获取授权时发生错误，参见 OAuth2 错误码。 使用 API 发生错误时，请参见 API 错误码。