Manual & Custom Authentication

Relevant source files

The following files were used as context for generating this wiki page:

• manual_custom_auth.py
• get_user_token.py
• oauth_auth.py
• main.py
• locales/en.json
• reset_machine_manual.py

The Manual & Custom Authentication feature provides a command-line interface for users to directly inject authentication credentials into the Cursor application. This allows for bypassing the standard browser-based OAuth flows (e.g., Google, GitHub) by manually providing a valid access_token or refresh_token. This tool is primarily for users who have obtained a token through alternative means and need to update the application's local authentication database.

The feature is invoked from the main application menu and orchestrates a series of prompts to gather the necessary information before committing it to the local database. It includes optional token validation and the ability to generate a random email if one is not provided.

Sources: main.py:471-473, manual_custom_auth.py

Core Workflow

The manual authentication process is a linear, interactive workflow executed in the command line. The user is guided through several steps to provide the necessary credentials, which are then saved to the Cursor application's local storage.

The following diagram illustrates the high-level flow of the manual_custom_auth.py script.

Component Breakdown

The manual authentication process is primarily handled by the manual_custom_auth.py script, which relies on the CursorAuth class for database interactions.

Sources: manual_custom_auth.py, oauth_auth.py

User Input and Validation

The script begins by collecting the required authentication details from the user through a series of prompts.

1. Token Input

The user is first prompted to enter their Cursor token. This can be either an access_token or a refresh_token. The script checks if a token was provided; if not, the process is aborted.

Sources: manual_custom_auth.py:33-38

2. Token Verification (Optional)

After a token is entered, the script attempts to verify its validity by calling check_user_authorized from the check_user_authorized.py module.

• On Success: A success message is displayed, and the process continues.
• On Failure: If the token is invalid, the process is aborted.
• On Error: If an exception occurs during verification (e.g., network error), the user is asked if they wish to proceed despite the error.
• Module Not Found: If check_user_authorized.py cannot be imported, the verification step is skipped entirely, and a warning is displayed.

Sources: manual_custom_auth.py:41-65

3. Email Input

The user is prompted for an email address.

• If an email is provided, it is used for the authentication record.
• If the input is left blank, the generate_random_email() function is called to create a placeholder email in the format cursor_<random_string>@cursor.ai.

Sources: manual_custom_auth.py:23-25, 68-74

4. Authentication Type

The user must select the authentication provider associated with the token.

Choice	Authentication Type
1	Auth_0 (Default)
2	Google
3	GitHub

Sources: manual_custom_auth.py:77-89

Confirmation and Database Update

Before making any changes, the script displays a summary of the provided information (token, email, and auth type) and asks for final confirmation from the user.

If the user confirms, the script initializes the CursorAuth class and calls its update_auth method. This method is responsible for writing the new credentials to the local Cursor authentication database. The provided token is used for both the access_token and refresh_token fields in the database.

Sources: manual_custom_auth.py:92-137, oauth_auth.py:404-410

The sequence diagram below shows the interactions between the user and the different script components.

User Interface Prompts

All user-facing text is sourced from language-specific JSON files, allowing for localization. The English prompts for this feature are defined in locales/en.json.

Prompt Purpose	locales/en.json Key	Default Text
Feature Title	manual_auth.title	Manual Cursor Authentication
Ask for token	manual_auth.token_prompt	Enter your Cursor token (access_token/refresh_token):
Token is missing	manual_auth.token_required	Token is required
Verifying token	manual_auth.verifying_token	Verifying token validity...
Token is valid	manual_auth.token_verified	Token verified successfully!
Token is invalid	manual_auth.invalid_token	Invalid token. Authentication aborted.
Ask for email	manual_auth.email_prompt	Enter email (leave blank for random email):
Random email notice	manual_auth.random_email_generated	Random email generated: {email}
Ask for auth type	manual_auth.auth_type_prompt	Select authentication type:
Final confirmation	manual_auth.confirm_prompt	Please confirm the following information:
Proceed prompt	manual_auth.proceed_prompt	Proceed? (y/N):
Update success	manual_auth.auth_updated_successfully	Authentication information updated successfully!
Update failure	manual_auth.auth_update_failed	Failed to update authentication information

Sources: locales/en.json:590-609

Conclusion

The Manual & Custom Authentication feature serves as a crucial tool for developers and advanced users who need to manage their Cursor authentication state directly. By providing a simple CLI to inject tokens, it offers a flexible alternative to the standard, browser-dependent OAuth procedures, facilitating testing, account recovery, and management of multiple authentication profiles.

Sources: manual_custom_auth.py