Device Login (OAuth Device Code)

RFC 8628 デバイス認証フロー。ブラウザのない CLI ログインのために、短命で制限された plm_ キーを発行します。

ブラウザを直接開けない CLI・ターミナル環境向けのログイン方式です。流れは 3 段階 —— コード要求（CLI が device_code と user_code を受け取る）→ ブラウザで承認（ユーザーが verification_url を開き、ログイン状態で user_code を入力）→ キーのポーリング（CLI が interval 秒ごとに token エンドポイントを呼び出し、承認が済むと plm_ キーを受け取る）です。

1. デバイスコードを要求#

POST/v1/auth/device/code

認証もボディも不要です。CLI は device_code を保持し、ユーザーに user_code と verification_url を案内します。expires_in（秒）以内に承認しないとコードは失効します。

200 OK

{
  "device_code": "f1d2c3b4a5...e9f0",
  "user_code": "WXYZ-1234",
  "verification_url": "https://router.pleum.ai/device",
  "interval": 5,
  "expires_in": 600
}

2. ブラウザで承認#

POST/v1/auth/device/authorize

ログイン済みのユーザーがブラウザで承認する段階のため、JWT 認証が必要です。ユーザーが verification_url に入力した user_code をボディとして送ると、そのデバイスコードがユーザーのアカウントに紐づきます。

パラメータ	型	必須	説明
user_code	string	必須	コード要求のレスポンスで受け取った `user_code`（例: `WXYZ-1234`）。

request body

{
  "user_code": "WXYZ-1234"
}

200 OK

{
  "ok": true
}

3. キーをポーリング#

POST/v1/auth/device/token

認証は不要です。CLI は device_code をボディとして送り、 interval 秒ごとにポーリングします。承認が完了すると、キーは plm_ キーとして一度だけ返されます。

パラメータ	型	必須	説明
device_code	string	必須	コード要求のレスポンスで受け取った `device_code`。

request body

{
  "device_code": "f1d2c3b4a5...e9f0"
}

200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

ポーリングのレスポンスステータス — 202 authorization_pending（未承認、ポーリングを継続）· 400 expired_token（コード失効）· 400 already_consumed（キーは発行済みで消費済み）· 404 invalid_device_code（存在しないコード）。

202 authorization_pending

{
  "detail": "authorization_pending"
}

全体フローの例#

全体フロー: コードを要求し、ユーザーがブラウザで承認するまで token エンドポイントをポーリングします。

curl

# 1. Request a device code (no auth)
curl -X POST https://router.pleum.ai/v1/auth/device/code

# -> { "device_code": "f1d2...e9f0", "user_code": "WXYZ-1234",
#      "verification_url": "https://router.pleum.ai/device",
#      "interval": 5, "expires_in": 600 }

# 2. Open verification_url in a browser and enter the user_code.

# 3. Poll for OAuth tokens every 5s until success (no auth).
curl -X POST https://router.pleum.ai/v1/auth/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "f1d2...e9f0"}'

# 202 -> still pending, wait 5s and poll again
# 200 -> { "access_token", "refresh_token", ... }  store them and stop polling

発行されるキーの制限#

このフローで発行されるキーは意図的に制限されています — 月次予算 monthly_budget_krw 5000、1 分あたりのリクエスト上限 rate_limit_rpm 10、そして 24 時間後に失効します。本番用途ではダッシュボードから正規のキーを発行してください。