APIで認証する

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

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

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

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

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

自分のユーザー情報を記述したJSONが返ってくれば、認証は成功しています。キーの作成や失効、それぞれの最終使用日時の確認については APIキーを管理する を参照してください。

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

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

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

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段階認証が有効になっている場合、ログインエンドポイントでは、認証アプリが生成する現在のTOTPコード、またはリカバリーコードのいずれかを含む code フィールドも必要です。
• API経由の登録もできます。POST /api/register は、ブラウザでのサインアップとまったく同じように、独自のアカウントを持つユーザーを作成してトークンを返します。

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

トークンを失効させる

方法は2つあります。

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

KolleKは、アプリからキーが作成または削除されたときにメールを送信するため、意図しないキーの操作を見逃すことはありません。ログインとセキュリティに関するアラートメール を参照してください。

次に読むページ

• レート制限と規約 でリクエストの規約を学びましょう。
• APIキーを管理する でトークンを管理しましょう。
• /docs/api の自動生成リファレンスで、すべてのエンドポイントを確認しましょう。