> For the complete documentation index, see [llms.txt](https://developers.hotishop.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.hotishop.com/open-api/usage/authentication.md).

# 使用 OAuth 进行身份验证

不管是公共应用和私有应用程序必须使用 OAuth 进行身份验证才能访问 Mshop 的 OpenAPI 资源。

## 访问流程

1. 发出公共应用的安装请求
2. 被安装应用重定向到 Mshop 应用页面（*需要登录* Mshop *后台并拥有应用中心相关权限*），并展示相关应用的详情（*包含Logo、名称、授权范围等*）
3. 点击安装应用后页面会重定向到应用授权的回调地址（redirect\_uri）完成安装授权
4. 回调地址 `redirect_uri` 中将包含`code` 与`hmac`
5. 公共应用开发者验证 `hmac` 后发送 `code` ,`client_key` 与`client_secret`  到 `https://{shop}.hotishop.com/api/admin/app_store/oauth/token` 换取访问令牌与授权范围
6. 商家打开已安装公共应用将会携带 `shop` ,`timestamp` 和`hmac` 参数访问应用的 `app_url` 目标地址
7. 开发者可使用获取到的访问令牌请求 Mshop OpenAPI 资源
8. Mshop 返回请求数据

## OAuth 授权相关的 API

{% hint style="warning" %}
 您首先需要获得开放应用的 Client\_key 与 Client\_secret 便用于之后的应用安装授权验证。
{% endhint %}

{% hint style="info" %}
如何获取 Client\_key 与 Client\_secret ？

联系 Mshop 官方客服人员，并提供您想要申请的开放应用的所需[权限范围](https://developers.hotishop.com/shi-yong-shuo-ming/quan-xian-lie-biao)（scopes）、应用访问地址（app\_url）、应用授权回调地址（redirect\_uris）等，通过申请后客服人员将发送 Client\_key 与 Client\_secret。
{% endhint %}

### 访问公共应用

> 需要后台登录

已登录商店的用户可以在应用市场安装您已发布的插件。

如果是使用开发者登记的`clinet_id` 与`redirect_uri` 进行安装，则访问以下`url`

```
https://{shop}.hotishop.com/admin/oauth/authorize?client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}&response_type=code
```

| 参数名            | 说明             | 必填 | 类型        | 限制                                                                            | 示例                         |
| -------------- | -------------- | -- | --------- | ----------------------------------------------------------------------------- | -------------------------- |
| shop           | 商店名称           | 是  | \[string] |                                                                               | shop                       |
| client\_id     | 公共应用 client id | 是  | \[string] |                                                                               |                            |
| redirect\_uri  | 访问授权回调地址       | 是  | \[string] |                                                                               |                            |
| response\_type | 响应类型           | 是  | \[string] | code                                                                          | code                       |
| scope          | 权限范围           | 是  | \[string] | [权限列表](https://developers.hotishop.com/shi-yong-shuo-ming/quan-xian-lie-biao) | read\_orders,write\_orders |

![应用安装页面](/files/-MjU9X3zet1_4kWLJzjh)

### 通过授权许可换取访问令牌

当用户确认点击【授权并安装】应用后，页面将被重定向开发者提供的`redirect_uri`地址，并传递验证参数。

```
https://example.com/auth/redirect_uri?code={authorization_code}&shop={shop}.hotishop.com&hmac={hmac}
```

| 参数名  | 说明     | 必填 | 类型        | 限制 | 示例 |
| ---- | ------ | -- | --------- | -- | -- |
| code | 授权code | 是  | \[string] |    |    |
| shop | 商店名称   | 是  | \[string] |    |    |
| hmac | hmac   | 是  | \[string] |    |    |

{% hint style="info" %}
验证 HMAC 请参考 [验证 HMAC](https://developers.hotishop.com/shi-yong-shuo-ming/ru-he-yan-zheng-hmac)
{% endhint %}

### 使用授权code置换token

开发者获取以上信息并通过 `HMAC` 验证后，可通过向商店的 `access_token`端点发送请求，使用授权 `code` 交换可访问 OpenAPI 的 `access_token`（*access\_token 暂定无限期*）。

```
POST /api/admin/app_store/oauth/token
```

#### Body参数

| 参数名            | 说明                 | 必填 | 类型        | 限制 | 示例 |
| -------------- | ------------------ | -- | --------- | -- | -- |
| client\_id     | 开放应用 client id     | 是  | \[string] |    |    |
| client\_secret | 开放应用 client secret | 是  | \[string] |    |    |
| code           | 授权 code            | 是  | \[string] |    |    |

**请求示例**

```
curl --location --request POST 'https://{shop}.hotishop.com/api/admin/app_store/oauth/token' \
--header 'Authorization: {access-token}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "client_id": "{client_id}",
    "client_secret": "{client_secret}",
    "code": "{authorization_code}"
}'
```

**示例响应内容**

```
{
    “access_token”: “6e9qGxq13F65o5Ecz45qQYK1NRJ9PiovvXNHc2qG”,
    “scope”: “read_orders,write_orders"
}
```

![应用安装完成](/files/-MjUD-er7YYcT2R6ikth)