# APIで認証する

すべてのAPIリクエストは、ベアラートークンによって認証されます。このページでは、何もない状態から最初のリクエストが成功するところまでを案内し、その後API自体でトークンを取得する方法と、トークンを失効させる方法を説明します。

以下の例に出てくる `https://kollek.example.com` は、お使いのインスタンスのアドレスに置き換えてください。APIはそのアドレスの `/api` 以下にあります。

## 最も手早い方法: アプリでキーを作成する

トークンを取得する最も簡単な方法は、プロフィールからAPIキーを作成することです。

::::steps
:::step title="APIキーを作成する"
アプリでプロフィール設定を開き、**APIキー**に移動します。キーを作成し、後で見分けられるようなラベル、例えば「レポート用スクリプト」を付けます。

::screenshot{label="新規キー作成フォームが表示されたプロフィール設定のAPIキーページ"}
:::

:::step title="トークンをコピーする"
トークンは作成直後の一度だけ表示されます。今すぐコピーして、パスワードマネージャーなど安全な場所に保管してください。紛失した場合は、そのキーを失効させて新しいキーを作成してください。
:::

:::step title="最初のリクエストを送る"
トークンは `Authorization` ヘッダーに入れて送信します。最初のリクエストとしては、自分自身のユーザー情報を返す `/api/me` が適しています。

```bash
curl https://kollek.example.com/api/me \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
```
:::
::::

自分のユーザー情報を記述したJSONが返ってくれば、認証は成功しています。キーの作成や失効、それぞれの最終使用日時の確認については [APIキーを管理する](https://getkollek.com/ja/docs/sekyuriti/api-ki-wo-kanri-suru) を参照してください。

:::note
トークンは自動的には失効しません。あなたが失効させるまで使い続けられるため、トークンはパスワードと同じように扱ってください。
:::

## APIを通じてトークンを取得する

自分の認証情報を管理するスクリプトや連携システムに向いた方法として、HTTPだけで完結する認証も可能です。

メールアドレスとパスワードでログインすると、トークンを受け取れます。

```bash
curl -X POST https://kollek.example.com/api/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password",
    "device_name": "Reporting script"
  }'
```

レスポンスの `data.token` にトークンが含まれます。任意の `device_name` を指定すると、後でキーの一覧からそのトークンを見分けやすくなります。

知っておくべき点が2つあります。

- ユーザーで[2段階認証](https://getkollek.com/ja/docs/sekyuriti/nidankai-ninsho)が有効になっている場合、ログインエンドポイントでは、認証アプリが生成する現在のTOTPコード、または[リカバリーコード](https://getkollek.com/ja/docs/sekyuriti/rikabari-kodo)のいずれかを含む `code` フィールドも必要です。
- API経由の登録もできます。`POST /api/register` は、ブラウザでのサインアップとまったく同じように、独自のアカウントを持つユーザーを作成してトークンを返します。

どちらのエンドポイントも1分あたり6リクエストに制限されています。実際のサインインには十分な回数であり、総当たり攻撃を防ぎます。

## トークンを失効させる

方法は2つあります。

- `DELETE /api/logout` は、そのリクエストを行ったトークン自体を失効させます。一時的なトークンを使うスクリプトが処理を終えたときに使います。
- プロフィールの**APIキー**ページには、すべてのトークンが一覧表示され、いずれも失効させられます。自動生成リファレンスにあるAPIキー関連のエンドポイントでも、HTTP経由で同じことができます。

KolleKは、アプリからキーが作成または削除されたときにメールを送信するため、意図しないキーの操作を見逃すことはありません。[ログインとセキュリティに関するアラートメール](https://getkollek.com/ja/docs/sekyuriti/sekyuriti-arato-meru) を参照してください。

## 次に読むページ

- [レート制限と規約](https://getkollek.com/ja/docs/kaihatsusha-to-api/reto-seigen-to-kiyaku) でリクエストの規約を学びましょう。
- [APIキーを管理する](https://getkollek.com/ja/docs/sekyuriti/api-ki-wo-kanri-suru) でトークンを管理しましょう。
- `/docs/api` の自動生成リファレンスで、すべてのエンドポイントを確認しましょう。