Device Authorization

Browser-based authentication flow for the CLI and headless environments. Neither endpoint requires auth — the CLI calls them before the user has a token.

Flow

  1. 1
    Request a code — POST /api/v1/device/authorize returns a one-time code and verification URL.
  2. 2
    Open browser — navigate to verification_uri. User logs in and clicks "Authorize".
  3. 3
    Poll for token — GET /api/v1/device/token?code=... every 2 seconds until api_token appears.
  4. 4
    Save token — write to ~/.kyper/config.yml with 0600 permissions.

Grants expire after 5 minutes. If the token endpoint returns 404, restart the flow. Rate limit: 5 requests/min on POST authorize.

POST /api/v1/device/authorize

Creates a new device grant. No auth or request body required.

bash 
curl -X POST https://kyper.shop/api/v1/device/authorize
json 
{
  "code": "A3F2B1C4",
  "verification_uri": "https://kyper.shop/device?code=A3F2B1C4"
}

GET /api/v1/device/token

Poll to check if the user authorized the grant. Pass ?code= from the authorize response.

bash 
curl "https://kyper.shop/api/v1/device/token?code=A3F2B1C4"
json 
// Waiting for user:
{"pending": true}

// Authorized:
{"api_token": "kpr_a1b2c3d4e5f6..."}

// Expired (5-min TTL) or invalid code — 404:
{"error": "Grant not found or expired"}