​

ADR-0010: grm CLI uses OAuth 2.0 Device Flow with long-lived API key storage

​

Status

​

Tags

​

Decision

​

Why

• Username/password flags — requires typing credentials into the terminal, incompatible with SSO/OAuth, stores a password at rest.
• Session cookie — browser-scoped, cannot be portably persisted across CLI invocations.
• Store the access token — access tokens are short-lived; agents would need to re-authenticate mid-task with no human present to approve.

​

Flow

grm auth login
  → POST /api/auth/device/code {client_id: "grm-cli"}
  ← {device_code, user_code, verification_uri, interval}
  → open browser to verification_uri
  → poll POST /api/auth/device/token every `interval` seconds
  ← {access_token} on user approval
  → POST /api/auth/api-key/create with Authorization: Bearer <access_token>
  ← {key: "ak_..."}
  → write {base_url, api_key} to ~/.config/grm/config.json
  → GET /api/auth/me with x-api-key to confirm and print email

​

Device approval page

​

Rules for agents

• Never store the access token to disk — exchange it for an API key immediately and discard
• The device page must require a confirmed session before rendering Approve/Deny
• grm auth whoami authenticates via x-api-key header, not Bearer token
• Config file permissions must be 0600 (owner read/write only)