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

取得存取權杖

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

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

:::tip

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

:::

あなた自分自身のアクセストークンは簡単に取得できるほか、あなたのアプリケーションを使用することになる不特定のユーザーのアクセストークンを取得することもできます。

• 前者の場合: 「自分自身のアクセストークンを手動発行する」 に進む
• 後者の場合: 「アプリケーション利用者にアクセストークンの発行をリクエストする」 に進む

自分自身のアクセストークンを手動発行する

Misskey Webの「設定 > API」で、自分のアクセストークンを発行できます。

:::danger

アクセストークンは他人に知られないようにしてください。

:::

アプリケーション利用者にアクセストークンの発行をリクエストする

アプリケーションを利用するユーザー(以下単に「ユーザー」と呼びます)のアクセストークンを取得するには、以下の手順で発行をリクエストします。

:::tip

以下に説明する方法は、アプリを作成せずインスタントにアクセストークンを発行する、MiAuthと呼ばれるものです。

アプリ作成方式でのアクセストークン取得方法もあります（旧来型）。 :::

Step 1

UUIDを生成する。以後これをセッションIDと呼びます。

:::danger

このセッションIDは毎回生成し、使いまわさないようにしてください。

:::

Step 2

アプリケーション認証フォームをユーザーのブラウザで表示させる。認証フォームは、以下の形式のURLで開くことができます:

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

ここで、

• {host}の部分は、ユーザーのサーバーのホストに置き換えます。通常ホストはユーザーが入力します。
• {session}の部分は、セッションIDに置き換えます。

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

名前	説明
name	アプリケーション名。
icon	アプリケーションのアイコン画像URL。
callback	認証が終わった後にリダイレクトするURL。 リダイレクト時には、sessionというクエリパラメータでセッションIDが付きます。
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

:::

Step 3

ユーザーがアプリケーションアクセスを許可した後、次の形式のURLにPOSTリクエストすると、レスポンスとしてアクセストークンを含むJSONが返ります。

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

ここで、

• 所有 HTTP API 均為 POST，請求和回應均為 JSON 格式（drive/files/create 除外）。
• 在請求標頭中指定 Content-Type: application/json。

レスポンスに含まれるプロパティは以下の通りです:

名前	説明
token	ユーザーのアクセストークン。
user	ユーザーの情報。

APIの利用

アクセストークンが取得できたら、各種エンドポイントにリクエストすることでAPIの利用が行えます。

:::tip

• HTTP APIはすべてPOSTで、リクエスト/レスポンスともにJSON形式です（drive/files/createを除く）。
• 要求ヘッダーにContent-Type: application/jsonを指定します。
• アクセストークンは、iというパラメータ名でリクエストボディJSONに含めます。
• ベースURLはhttps://{サーバーのドメイン}/apiです。

:::

アクセストークン付きのボディの例（metaの場合）:

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

APIの詳細は、APIリファレンスを参照してください。

:::warning

MisskeyはRESTを採用していません。

:::

また、MisskeyはHTTP APIだけでなく、ストリーミングAPIも提供しています。ストリーミングAPIの詳細はこちらのドキュメントを参照してください。