jointrashposs/content/tw/docs/4.for-developers/api/token.md

# 取得存取權杖

要開始使用 API，您需要取得與將使用API的帳戶相關聯的**存取權杖**。
本文件將介紹取得存取權杖的步驟，然後說明如何使用基本 API。

基本上，API需要存取權杖進行請求。
存取權杖是與用戶關聯的身份驗證資料，用於識別使用API的用戶，同時管理每個存取權杖具有什麼樣的操作權限。

:::tip
使用者和與該使用者關聯的存取權杖之間存在一對多關係，並且可以向​​使用者發行多個存取權杖。
:::

你可以輕鬆地獲得自己的存取權杖，也可以獲取使用你的應用程序的不特定用戶的存取權杖。

- 如果是前者：**閱讀「手動發行您自己的存取權杖」**
- 如果是後者：閱讀「**請求應用程式使用者發行存取權杖**」

### 手動發行您自己的存取權杖

您可以在 Misskey Web 的「設定 > API」中發行自己的存取權杖。

:::danger
請不要與他人分享您的存取權杖。
:::

### 請求應用程式使用者發行存取權杖

若要為使用應用程式的使用者（以下簡稱「使用者」）取得存取權杖，請依照下列步驟請求核發。

:::tip

下面描述的方法稱為 MiAuth，它無需創建應用程式即可立即發行存取權杖。

[還有一種獲取存取權杖的方法是使用應用程式建立方法（舊方法）。](./app)
:::

#### 步驟1

產生 UUID。從現在起，這將被稱為**工作階段ID**。

:::danger
此工作階段 ID 應每次生成，不應重複使用。
:::

#### 步驟2

在使用者瀏覽器中顯示應用程式授權表單。授權表格可透過以下格式的網址開啟：

```
https://{host}/miauth/{session}
```

需要變更的部份

- 將 `{host}` 替換為使用者伺服器的主機。主機通常由使用者輸入。
- 將 `{session}` 替換為工作階段 ID。

您也可以在網址中設定多個選項作為查詢參數：

| 名稱           | 說明                                                                  |
| ------------ | ------------------------------------------------------------------- |
| `name`       | 應用程式名稱。                                                             |
| `icon`       | 應用程式的圖標圖像網址。                                                        |
| `callback`   | 驗證後重導向的網址。<br>重導向時，工作階段 ID 會附加到查詢參數 `session`。                      |
| `permission` | 應用程式所需的權限。<br>列舉所請求的授權，以半形逗號 `,` 分隔。可以在[此處](./permission.md)查看權限清單。 |

:::tip{label='例'}

```
https://misskey.io/miauth/c1f6d42b-468b-4fd2-8274-e58abdedef6f?name=MyApp&callback=https%3A%2F%2Fmyapp.example.com%2Fcallback&permission=write:notes,write:following,read:drive
```

:::

#### 步驟3

使用者授予應用程式存取權限後，向下列格式的網址傳送 POST 請求，將傳回一個包含存取權杖的 JSON 作為回應。

```
https://{host}/api/miauth/{session}/check
```

需要變更的部份

- 將 `{host}` 替換為使用者伺服器的主機。
- 將 `{session}` 替換為工作階段 ID。

回應中包含的屬性有：

| 名稱      | 說明        |
| ------- | --------- |
| `token` | 使用者的存取權杖。 |
| `user`  | 使用者資料。    |

## 使用API

取得存取權杖後，就可以透過向各種端點發出請求來使用API。

:::tip

- 所有 HTTP API 均為 POST，請求和回應均為 JSON 格式（drive/files/create 除外）。
- 在請求標頭中指定 `Content-Type: application/json`。
- 存取權杖包含在請求內文 JSON 中，參數名為 `i`。
- 基礎網址是 `https://{伺服器網域}/api`。

:::

帶有存取權杖（中介資訊）的正文範例：

```json
{
    "i": "HogEFugA1341",
    "detail": false
}
```

<!--TODO:「APIリファレンス」をリンクに差し替え-->

有關 API 的更多資訊，請參閱 API 參考。

:::warning
Misskey 不使用 REST。
:::

此外，Misskey 不僅提供 HTTP API，還提供資料流 API。有關資料流 API 的詳細資訊，請參閱[此文件](./streaming/index.md)。