OAuth2 Device Authorization Grant (RFC 8628) for TV/CLI clients #13

New Issue

Claude · 2026-03-07T00:03:36Z

Claude commented

2026-03-07 00:03:36 +00:00

Summary

Add support for the Device Authorization Grant (RFC 8628) to enable authentication from devices without a browser — Apple TV, Roku, CLI tools, etc.

How it works

Device requests a code: POST /oauth/device → gets device_code + user_code + verification_uri
Device displays: "Go to auth.example.com/device and enter code: ABCD-1234"
User opens phone/laptop, visits URL, enters code, logs in
Device polls: POST /oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code
Once user approves, device gets access token + refresh token

Use case

The planned Canister tvOS app (TVML/TVMLKit) needs to authenticate with Clinch. A TV remote is not a great way to type passwords, making this the standard solution.

Also useful for CLI tools and any device with a screen but no browser.

Endpoints needed

POST /oauth/device — issue device + user codes
GET /device — user-facing page to enter the code
POST /oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code — device polls this

Notes

User code should be short and unambiguous (e.g., ABCD-1234, no 0/O confusion)
Polling interval enforced server-side (typically 5s)
Codes expire (typically 15 minutes)
Standard responses during polling: authorization_pending, slow_down, expired_token, access_denied

Priority

Low — this is for the tvOS app which is further down the roadmap. Logging it now since it came up in the discussion about OAuth grant types.

## Summary Add support for the [Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628) (RFC 8628) to enable authentication from devices without a browser — Apple TV, Roku, CLI tools, etc. ## How it works 1. Device requests a code: `POST /oauth/device` → gets `device_code` + `user_code` + `verification_uri` 2. Device displays: "Go to auth.example.com/device and enter code: ABCD-1234" 3. User opens phone/laptop, visits URL, enters code, logs in 4. Device polls: `POST /oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code` 5. Once user approves, device gets access token + refresh token ## Use case The planned Canister tvOS app (TVML/TVMLKit) needs to authenticate with Clinch. A TV remote is not a great way to type passwords, making this the standard solution. Also useful for CLI tools and any device with a screen but no browser. ## Endpoints needed - `POST /oauth/device` — issue device + user codes - `GET /device` — user-facing page to enter the code - `POST /oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code` — device polls this ## Notes - User code should be short and unambiguous (e.g., `ABCD-1234`, no `0`/`O` confusion) - Polling interval enforced server-side (typically 5s) - Codes expire (typically 15 minutes) - Standard responses during polling: `authorization_pending`, `slow_down`, `expired_token`, `access_denied` ## Priority Low — this is for the tvOS app which is further down the roadmap. Logging it now since it came up in the discussion about OAuth grant types.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dkam/clinch#13