Device Authorization

Authorize CLI tools and headless AI clients to access your Levelup account using the device code flow.

Device authorization lets you grant access to AI clients and CLI tools that cannot open a browser-based login flow on their own. This is commonly used by MCP servers running inside tools like Claude, Cursor, or terminal-based applications.

How the Device Authorization Flow Works

The device code flow follows this sequence:

The device requests a code -- Your AI client or CLI tool contacts Levelup and receives a short code (formatted as XXXX-XXXX) and a URL.
You enter the code in your browser -- Open the URL provided by the device (or navigate to the device authorization page in Levelup) and enter the code.
You approve or deny access -- After verifying the code, you select which organization the device can access and click Approve (or Deny to block the request).
The device receives a token -- Once approved, the device automatically receives an MCP token and can begin accessing your financial data.

Step 1: Start the Flow from Your AI Client

When your AI client or CLI tool needs to access Levelup data, it will display:

A device code (for example, ABCD-EFGH)
A URL to visit in your browser

Some tools may also provide a direct link that pre-fills the code for you.

Step 2: Enter the Device Code

Open the device authorization page in your browser. You can navigate to it from the URL displayed by your tool, or go to it directly within Levelup.
Enter the 8-character device code in the input field.
Click Continue.

The code is case-insensitive and the hyphen is optional -- you can type ABCDEFGH or ABCD-EFGH.

Step 3: Review and Approve

After entering a valid code, you see an approval page with:

Device Code -- The code you entered, for confirmation.
Account -- Your email address.
Client -- The client application that requested access.
Scope -- The permissions being requested (typically read:financial).
Expiration -- How many minutes until the code expires.
Organization selector -- If you belong to multiple organizations, choose which one the device can access.

Review the information, then:

Click Approve to grant the device read-only access to the selected organization's financial data.
Click Deny to reject the request. The device will be notified that access was denied.

Choosing an Organization

If you are a member of multiple organizations, a dropdown lets you select which organization the device token is scoped to. The device will only be able to access financial data for that organization.

Step 4: Confirmation

After approving:

A confirmation screen shows that the device has been authorized along with the selected organization name.
The device (your AI client or CLI tool) automatically receives its access token and can begin querying your data.
You can close the browser window.

After denying:

A confirmation screen shows that the request was denied.
The device is notified that access was blocked.

Security Considerations

Device codes expire -- Each code is valid for a limited time (shown on the approval page). Expired codes cannot be used.
One-time use -- Each device code can only be approved or denied once. After it has been used, it cannot be reused.
Read-only access -- Device authorization creates an MCP token with read:financial scope only. The device cannot modify your data.
Tokens can be revoked -- After approving a device, you can revoke its token at any time from the MCP Tokens settings page.
Unrecognized requests -- If you see a device authorization page but did not initiate a request from any AI tool, click Deny or simply close the page.

Separately from the device authorization flow, Levelup may block sign-in attempts from unrecognized devices for security. If this happens:

You see a "New Device Detected" page after attempting to sign in.
A verification email is sent to your registered email address.
Open the email and click Approve Login to verify the device.
The verification link expires in 15 minutes.

If you did not initiate the login, click Deny Login in the email to block the attempt.