Device Authorization

Why Device Authorization?

Device authorization lets apps on another device (desktop apps, plugins, CLIs) sign users in without opening a full browser. Typical use cases:

• Figma or IDE plugins.
• Native desktop apps.
• Command‑line tools or headless devices.

Activate Device Authorization

Enable the feature in your auth constants:

With deviceAuthorization: true, the /device-authorization/[code] route becomes available. Users can open this page on another device to approve or deny the sign-in attempt.

Set DEVICE_AUTHORIZATION_CLIENT_ID to a unique string in your Convex environment variables:

How the flow works

On the device / plugin:

• Call the Convex mutation deviceAuthorization.requestDeviceCode with your clientId.
• Show the returned user_code and instruct the user to open https://your-app.com/device-authorization/[user_code] in a browser.
• Poll the deviceAuthorization.getDeviceCodeStatus query using the device_code.
• Once the status becomes approved, call deviceAuthorization.createDeviceToken to fetch an access token for the device and store it.
• Pass the access_token to your app’s auth integration. If you’re using createSvelteAuthClient, set externalSession.accessToken (as shown in the example below).

In the browser, the /device-authorization/[code] page uses authClient.device to validate the user_code and lets the user approve or deny the request.

Minimal Svelte client example

This example shows how a Svelte app (or plugin UI) can start the device flow using Convex: