Device Login (OAuth Device Code)

RFC 8628 디바이스 인증 플로우. 브라우저가 없는 CLI 로그인을 위해 수명이 짧고 제한된 plm_ 키를 발급합니다.

브라우저를 직접 띄울 수 없는 CLI·터미널 환경을 위한 로그인 방식입니다. 흐름은 세 단계입니다 — 코드 요청(CLI가 device_code와 user_code를 받음) → 브라우저 승인(사용자가 verification_url을 열고 user_code를 입력해 로그인 상태로 승인) → 키 폴링(CLI가 interval초마다 토큰 엔드포인트를 호출해 승인이 끝나면 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

{
  "key": "plm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

폴링 응답 상태 — 202 authorization_pending(아직 미승인, 계속 폴링) · 400 expired_token(코드 만료) · 400 already_consumed(이미 키를 발급해 소진됨) · 404 invalid_device_code(존재하지 않는 코드).

202 authorization_pending

{
  "detail": "authorization_pending"
}

전체 흐름 예시#

코드를 요청하고, 사용자가 브라우저에서 승인할 때까지 토큰 엔드포인트를 폴링하는 전체 흐름입니다.

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 the key 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 -> { "key": "plm_..." }  store it and stop polling

발급되는 키의 제한#

이 플로우로 발급되는 키는 의도적으로 제한됩니다 — 월 예산 monthly_budget_krw 5000, 분당 요청 한도 rate_limit_rpm 10, 그리고 24시간 후 만료. 운영용으로는 대시보드에서 정식 키를 발급해 사용하세요.