TVs, devices and bots
The device flow (RFC 8628) for things without a good keyboard or browser.
The device shows a short code; the user types it on their phone or computer, approves, and the device picks up its tokens.
Building a bot in Node.js?
The Bot SDK (@castyr/bots-auth) does everything on this page for you, including saving
links and renewing tokens.
Ask for a code
curl -X POST https://sso.castyr.cloud/oauth/device/code \
-d client_id=YOUR_CLIENT_ID \
-d scope="identify" \
-d platform_name="Castyr for Roku" \
-d platform_description="Watch your streams on the big screen" \
-d platform_icon=https://cdn.yourapp.example/icon.pngProp
Type
Text with control or invisible characters, and values that are too long, are rejected with
invalid_request rather than cut short. The user always sees these details marked as unverified.
{
"device_code": "…",
"user_code": "BDKQ-7FWX",
"verification_uri": "https://sso.castyr.cloud/activate",
"verification_uri_complete": "https://sso.castyr.cloud/activate?user_code=BDKQ-7FWX",
"expires_in": 600,
"interval": 5,
"confirmation_phrase": "GentleKoala"
}Show the code and the phrase
Display user_code and verification_uri; a QR code of verification_uri_complete saves typing.
Always show confirmation_phrase too
The user has to pick it out of three choices to approve, which proves they can see your screen. A wrong pick
cancels the request. Keep device_code secret: it is what claims the tokens.
Bot apps get /activate/bot as their page.
Poll for tokens
curl -X POST https://sso.castyr.cloud/oauth/token \
-d grant_type=urn:ietf:params:oauth:grant-type:device_code \
-d device_code=DEVICE_CODE \
-d client_id=YOUR_CLIENT_IDWait interval seconds between polls. Until the user finishes you get an error; keep going on the first two:
error | Meaning | Do |
|---|---|---|
authorization_pending | Not approved yet | Poll again after interval |
slow_down | Polling too fast | Add 5 seconds to your interval, then keep polling |
access_denied | Denied, or the wrong phrase was picked | Stop; offer to start again |
expired_token | 10 minutes passed | Stop; ask for a new code |
After approval, the next poll returns tokens in the usual shape, exactly once. TV / device and
bot apps also get a refresh_token, so they stay signed in without asking again.
Users see every device and bot signed in to their account under Account → Devices, and can sign any of them out. When they do, your tokens stop working at once.