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 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.
• Open the returned verification_uri_complete 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. In the Svelte example below, setupAuth() reacts to externalSession.accessToken and exchanges it for a Convex JWT.

In the browser, the /device page reads user_code from the query string, uses authClient.device to validate it, 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: