# 取得存取權杖
要開始使用 API,您需要取得與將使用API的帳戶相關聯的**存取權杖**。
本文件將介紹取得存取權杖的步驟,然後說明如何使用基本 API。
基本上,API需要存取權杖進行請求。
存取權杖是與用戶關聯的身份驗證資料,用於識別使用API的用戶,同時管理每個存取權杖具有什麼樣的操作權限。
:::tip
你可以輕鬆地獲得自己的存取權杖,也可以獲取使用你的應用程序的不特定用戶的存取權杖。
:::
あなた自分自身のアクセストークンは簡単に取得できるほか、あなたのアプリケーションを使用することになる不特定のユーザーのアクセストークンを取得することもできます。
- 前者の場合: **「自分自身のアクセストークンを手動発行する」** に進む
- 後者の場合: **「アプリケーション利用者にアクセストークンの発行をリクエストする」** に進む
### 自分自身のアクセストークンを手動発行する
Misskey Webの「設定 > API」で、自分のアクセストークンを発行できます。
:::danger
アクセストークンは他人に知られないようにしてください。
:::
### アプリケーション利用者にアクセストークンの発行をリクエストする
アプリケーションを利用するユーザー(以下単に「ユーザー」と呼びます)のアクセストークンを取得するには、以下の手順で発行をリクエストします。
:::tip
以下に説明する方法は、アプリを作成せずインスタントにアクセストークンを発行する、MiAuthと呼ばれるものです。
[アプリ作成方式でのアクセストークン取得方法もあります(旧来型)。](./app)
:::
#### 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` | アプリケーションが要求する権限。
要求する権限を`,`で区切って列挙します。権限の一覧は[こちら](./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
```
:::
#### 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の場合):
```json
{
"i": "HogEFugA1341",
"detail": false
}
```
APIの詳細は、APIリファレンスを参照してください。
:::warning
MisskeyはRESTを採用していません。
:::
また、MisskeyはHTTP APIだけでなく、ストリーミングAPIも提供しています。ストリーミングAPIの詳細は[こちらのドキュメント](./streaming/index.md)を参照してください。