BDFK-RSTV. The user opens a URL on their phone or laptop, signs in, types the code, and the waiting device’s next poll returns { authorized: true, user_id }. No password ever travels through the constrained device. When auth.session is configured, the same response also carries an access_token, a theAuth session token the device can send as Authorization: Bearer .... To issue a different credential (a JWT, a scoped API token), pass issueToken to the plugin. Without either, the response only confirms who approved, and your app decides what to issue next.
Setup
1
Add the plugin
lib/theauth.ts
deviceCodes secondary storage, which is process memory by default. Memory is lost on restart and is not shared between instances, so on more than one instance or on serverless set secondaryStorage: 'database' (or Redis) on createTheAuth. See Secondary storage. Device codes and user codes are stored only as SHA-256 hashes.2
Build the user-facing approval page
Create a page at yourverificationUri. It should let a signed-in user enter the code the device is showing and approve or deny the request.app/device/page.tsx (Next.js)
/auth/device/authorize endpoint requires an authenticated user (from auth.adapter or an auth.session token), and always takes the user from that session. A user_id in the body is ignored. The request must use Content-Type: application/json, and a browser Origin that is neither the origin of verificationUri nor listed in trustedOrigins is refused with 403. This stops another site from approving a code on a signed-in user’s behalf. action is 'approve' (the default) or 'deny'.Device flow
1
Request codes (on the device)
POST /auth/device/codeThe device calls this endpoint to start a new authorization attempt. No authentication required. The body is optional JSON (or form-encoded) with client_id and scope, which are remembered on the grant and passed to issueToken.CLI tool
user_code prominently, this is what the user types. verification_uri_complete includes the code as a query parameter, so you can also show a QR code for it.2
Poll for authorization (on the device)
POST /auth/device/tokenPoll this endpoint at the interval returned in the previous step (default: every 5 seconds). Keep polling until you get an authorized response or the code expires. While the grant is pending the endpoint answers 400 with error: 'authorization_pending'. The body is { device_code }, plus an optional grant_type that must be urn:ietf:params:oauth:grant-type:device_code if sent.CLI tool
3
User approves (on the secondary device)
The user opensverification_uri on their phone or laptop, signs in, and enters the code. The approval page calls /auth/device/authorize with the user code and action: 'approve'. The next poll from the device returns { authorized: true, user_id: '...' } (plus the token fields described below). A denied grant returns access_denied instead. A grant can be exchanged once: a second poll after success gets expired_token.User code format
User codes use the formatXXXX-XXXX, two four-character segments separated by a hyphen. The character set is consonants only (BCDFGHJKLMNPQRSTVWXZ), which avoids:
- Visually ambiguous characters (no
0/O,1/I,5/S) - Characters that read awkwardly when pronounced aloud
codeLength option controls the length of each segment (default: 4).
Input on the approval page is case-insensitive and whitespace-tolerant, bdfk rstv, BDFK-RSTV, and BDFKRSTV all resolve to the same grant.
Polling interval and rate limits
The initial interval is returned by the/auth/device/code endpoint (default: 5 seconds). Use it as your starting poll delay.
If a device polls again before the interval has passed, /auth/device/token answers 400 with error: 'slow_down' and a new interval that is 5 seconds longer, as RFC 8628 requires. The counter is kept in secondary storage, so it holds across instances. Use the new interval for all later polls.
Three more limits apply:
- Guessing user codes: each approving user gets 5 wrong codes per 15 minutes (
userCodeAttemptLimit,userCodeAttemptWindowSeconds). Further attempts get429. - Built in: the plugin throttles
/auth/device/codeand/auth/device/authorizeto 30 requests per minute per IP and answers429with{ "error": "Rate limit exceeded" }. These counters are in process memory. - Optional: add the
rateLimit()plugin for shared, configurable limits on all three endpoints (defaults: 10 per minute forcode, 60 fortoken, 20 forauthorize).
Endpoints
Errors from
/auth/device/authorize: 401 login_required (no signed-in user), 403 access_denied (cross-origin request), 400 invalid_request (missing or unknown code, code already handled, bad action, wrong content type), and 429 after too many wrong codes.
/auth/device/code response
/auth/device/token responses
An approved grant returns 200 with { "authorized": true, "user_id": "..." }. When a token is issued, the body also has access_token, token_type (Bearer), and, if known, expires_in, refresh_token and scope. Every other state returns 400 with an error code and an error_description:
Configuration reference
Without the plugin,
createDeviceAuthModule takes the same options plus resolveUser(request), which must return the signed-in user for approvals to work. You then route requests through module.handleRequest(request). See CLI login for a ready-made client.
Related
Authentication overview
All sign-in methods available in theAuth.
Magic link
Another passwordless flow for devices that can open a browser.
Sessions
How theAuth manages session lifetime and cookie settings.
CLI login
The
theauth login command and loginWithDeviceFlow client.MCP
Agent-to-tool authentication for MCP servers.