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

取得存取權杖

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

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

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

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

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

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

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

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

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

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

:::tip

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

還有一種獲取存取權杖的方法是使用應用程式建立方法（舊方法）。 :::

步驟1

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

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

步驟2

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

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

需要變更的部份

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

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

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

:::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。

:::

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

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

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

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

此外，Misskey 不僅提供 HTTP API，還提供資料流 API。有關資料流 API 的詳細資訊，請參閱此文件。