Cursor API Endpoints

Relevant source files

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

• check_user_authorized.py
• cursor_acc_info.py
• cursor_auth.py
• config.py
• manual_custom_auth.py
• main.py
• locales/en.json

Introduction

This document outlines the external Cursor API endpoints that are consumed by the cursor-free-vip tool. The project itself does not host these APIs but contains various scripts and modules designed to interact with them for purposes such as user authentication, authorization checking, and account information retrieval. The primary interactions revolve around verifying user tokens, fetching account status, and managing local authentication state based on the API responses.

The main functionalities provided by this toolset include checking if a user token is authorized, retrieving account subscription and usage details, and manually setting authentication tokens. These operations rely on specific endpoints hosted at cursor.sh and a separate token refresh server configured within the project.

API Interaction Architecture

The scripts within this repository act as clients to the Cursor backend services. The general flow involves reading a locally stored token, sending it in an Authorization header to a specific endpoint, and processing the JSON response.

Key API Endpoints

The following table summarizes the primary external API endpoints used by the tool.

Method	Endpoint	Description	Used In -
GET	https://cursor.sh/api/user/info	Fetches user account information, including subscription status.	check_user_authorized.py, cursor_acc_info.py -
GET	https://cursor.sh/api/user/usage	Retrieves the user's API usage statistics.	check_user_authorized.py, cursor_acc_info.py -
POST	https://token.cursorpro.com.cn	Refreshes the user's access token. The exact endpoint path is /refresh.	config.py (defines server), locales/en.json (defines text strings for this action) -
GET	https://api.github.com/repos/...	Checks for the latest release version of the cursor-free-vip tool.	main.py, scripts/install.ps1, scripts/install.sh -

User Authorization Check

The check_user_authorized.py script is a key component for verifying if a user's token is valid and authorized. It can source the token from the local database or accept it via manual input.

Sources: check_user_authorized.py, locales/en.json

Authorization Flow

The following diagram illustrates the process of checking user authorization.

Logic Details

1. The script prompts the user to either use a token from the local database or provide one manually.
2. It constructs a headers dictionary containing the Authorization: Bearer <token>.
3. It makes a GET request to https://cursor.sh/api/user/info.
4. If the status code is 200, it proceeds to make a second GET request to https://cursor.sh/api/user/usage.
5. If both requests return 200, the user is considered authorized.
6. Any other status code (like 401 Unauthorized) indicates an invalid or unauthorized token.

Sources: check_user_authorized.py:80-112

Token Refresh Mechanism

The application includes a mechanism to refresh authentication tokens, although the refresh logic itself is not fully implemented in the provided scripts. The configuration, however, points to the server responsible for this process.

Configuration

The token refresh behavior is defined in the config.ini file, managed by config.py.

Section	Key	Default Value	Description
Token	refresh_server	https://token.cursorpro.com.cn	The base URL for the token refresh service.
Token	enable_refresh	True	A flag to enable or disable the refresh feature.

Sources: config.py:110-113

User Experience

The locales/en.json file contains strings that describe the user-facing messages during the token refresh process, indicating that this is an intended feature.

• token.refreshing: "Refreshing token..."
• token.refresh_success: "Token refreshed successfully! Valid for {days} days (expires: {expire})"
• token.refresh_failed: "Token refresh failed: {error}"

Sources: locales/en.json:token

Manual Authentication

The manual_custom_auth.py script provides a command-line interface for a user to manually input their token and associate it with an email address in the local authentication database.

Sources: manual_custom_auth.py, cursor_auth.py

Manual Authentication Flow

This diagram shows the steps involved in the manual authentication process.

Database Update

After successful verification and confirmation, the CursorAuth class is used to update the local SQLite database (state.vscdb) with the new authentication information. It updates or inserts records for the user's email, access token, and authentication type (Auth_0, Google, or GitHub).

Sources: manual_custom_auth.py:102-108, cursor_auth.py:73-98

Conclusion

The cursor-free-vip repository provides a suite of client-side tools for interacting with several key Cursor API endpoints. These interactions are fundamental to the tool's core features, enabling user authorization checks, account information retrieval, and local management of authentication credentials. While the APIs themselves are external, the scripts and configuration files clearly define how the tool communicates with them to achieve its objectives.