Cross-device onboarding: keep the task intact when users switch screens
Design device-code onboarding across both screens, including account choice, code expiry, cancellation and confirmation that the original app is ready.
In this article
Cross-device onboarding succeeds when the original app can perform the next useful task. Approval in a browser is only one step toward that result. Both screens need to explain what is happening, which account is involved and where the person should continue.
Device-code authorization makes the gap easy to see. A desktop tool, television or command-line application displays a code. The user opens a browser elsewhere to approve access. Meanwhile, the original device waits for confirmation. If either side declares the whole task finished too early, the user has to work out which screen is telling the truth.
Design the two screens as one journey
Consider an illustrative desktop publishing tool that needs the user to connect a cloud workspace. The desktop app displays a code and a verification address. The person opens the address on a phone, signs in and approves the connection.
The browser now knows that approval occurred. The desktop app still needs to receive the result and open the correct workspace. Its interface should show that transition instead of relying on the person to infer it from the phone’s success screen.
GitHub’s device-flow documentation describes this separation: the app obtains codes and a verification URL, the user authorizes in a browser, and the app polls for the authorization result. That is documented behavior for GitHub’s flow, not proof that every cross-device product uses the same implementation.
For design, the important consequence is a shared task with distinct states on each surface. Write the destination and confirmation for both before polishing the code-entry screen.
Make the device being authorized recognizable
The browser should explain which application or device is requesting access and what the approval enables. The person may already be signed in on the phone with a personal account while the desktop work belongs to a company account. Make that account choice visible before approval.
The OAuth device authorization standard, RFC 8628, discusses the risk of a user authorizing a device they do not possess. It recommends helping the person recognize the device and confirm that it is theirs. This is part of a usable approval decision, not an optional warning to hide below the action.
In the publishing-tool example, the browser can show the application name and the selected workspace identity. If the product supports choosing a workspace after authorization, explain that the choice is still ahead. Do not imply that approving an account has already selected the right project or organization.
A QR code can reduce typing, but it should not erase the user’s opportunity to understand what they are connecting. Preserve a readable route for people who cannot or do not want to scan it.
Help the user enter the code they can see
Code presentation needs to work across distance, screen size and input method. Keep it legible, separate it from unrelated identifiers, and explain where it goes. The code used by the person should not be confused with a technical identifier retained by the application.
RFC 8628 includes usability guidance on avoiding ambiguous characters and handling formatting added for readability. Apply the chosen system’s actual rules; a product team should not invent more permissive parsing without considering the authorization service’s behavior.
If the person enters a code that is not valid, keep the explanation local to that action. Let them inspect the code on the originating screen and retry within the supported limits. Avoid a generic account error that sends them to reset a password when the account sign-in succeeded.
A copy control can help when both surfaces are on the same computer. On a television-to-phone journey, a short readable code and address may matter more. Review the real device pairing instead of assuming one layout serves every situation.
Expiration needs a coordinated restart
When a code expires, the original app should say so and offer a deliberate way to obtain a new one. Replacing it silently while the person is typing on another device can create an avoidable mismatch.
GitHub documents an expiry window and a separate polling interval, along with pending, denied and expired outcomes. Those are different concerns. A code’s lifetime is not an instruction to poll continuously, and a pending response is not an error the user caused.
In the illustrative tool, generating a replacement should update the originating screen and explain that the old code no longer applies. The browser should also have a useful ending for an expired submission: return to the original app for a fresh code, rather than repeatedly retry the same one.
Do not carry a countdown beyond the point at which the actual server state is known to be expired. Equally, do not invent a precise lifetime if the integration has not supplied one. The display needs to follow the authorization system.
Cancellation should stop the right work
A person can cancel in the browser, close the originating app, or decide that the wrong account is selected. These actions should not all leave an indefinite waiting screen.
When the application receives a denial, show an accurate canceled state with a way to restart intentionally. If it stops listening because the local task was canceled, make that state visible. Any later approval must be reconciled with the current task rather than unexpectedly opening a connection the user abandoned.
The product also needs an answer for approval that happened while the original app was offline. The browser should avoid claiming that the disconnected app is already ready. On return, the app should check the current state and either continue or explain why a new authorization is required.
These decisions belong in the integration contract. Copywriters cannot settle them by choosing a more reassuring success message.
Confirm readiness on the original screen
The desktop publishing tool should finish by naming the connected account or workspace and offering the action the user came to perform. If a workspace choice remains, present it. If permissions are insufficient for the task, explain the remaining limitation.
A final browser message can direct the person back to the app. It should not be the only record of completion. The original screen is where the user needs to understand whether the connection is usable.
Review the journey with a wrong account, an expired code, cancellation and temporary loss of connectivity. Check both screens after each transition. The setup recovery guide covers preserving intent across a return.
The useful ending is a recognizable workspace and a working next action. Once both screens agree on that state, the handoff has done its job.
