deepscan-login

DeepScan Login Authorization

All script paths are relative to this Skill directory.

Two login methods are supported:QR code login and API Key login。

Step 1: Check whether already logged in

python scripts/auth.py get-token

• Returns {"token": "..."} → already logged in, skip to Token Usage。
• Exit code is 1 → not logged in, choose a login method below according to the scenario.

---

Method A: API Key Login

When the user directly provides an API Key (such as in the sk-xxxx or eyJxxx format), simply save it:

python scripts/auth.py save-token {api_key}

Tell the user: The API Key has been saved, login successful, and you can start using the scan code book feature.

---

Method B: QR Code Login

When the user initiates login but does not provide an API Key, use the QR code scanning flow.

Step 2: Initiate authorization

python scripts/auth.py initiate

Example return:

{
  "token": "qIksuKLU",
  "auth_url": "https://qr67.cn/auth/qIksuKLU",
  "qrcode_path": "/tmp/deepscan_qr_qIksuKLU.png",
  "expires_in": 300
}

Record the returned token, which is needed for subsequent polling.

Step 3: Display the QR code and prompt the API Key option

Provide the QR code through the following two methods at the same time, ensuring the user can scan it in any environment:

Method one: Image (supported by some Agents)

Use the Read tool to read the PNG image pointed to by qrcode_path , and display it directly to the user.

Method two: Browser link (universal)

Concatenate auth_url to the text parameter of the Caoliao QR code generation link:

https://mh.cli.im/?text={auth_url}

For example, if auth_url is https://qr67.cn/auth/qIksuKLU, then the link is:

https://mh.cli.im/?text=https://qr67.cn/auth/qIksuKLU

Tell the user:

Please scan the QR code above, or click this link to open the QR code in a browser and scan it, then use the "Caoliao Scanner" WeChat mini program to complete the login authorization. The QR code is valid for 5 minutes.

You can also directly provide an API Key to complete login (skipping QR code scanning).

Step 4: Wait for the user to scan the QR code

If the user provides an API Key during the waiting period, directly skip toMethod A and save it; no need to continue polling.

Execute once every 5 seconds, up to 60 times (300 seconds in total):

python scripts/auth.py poll {token}

• Returns {"success": false} → the user has not yet scanned the QR code, continue waiting.
• Returns {"success": true, "api_key": "eyJ..."} → authorization successful, record api_key, and proceed to Step 5.
• Still not successful after 60 times → tell the user the QR code has expired and login can be initiated again.

During polling, use sleep 5 to wait, and do not output each polling result to the user.

Step 5: Save the login credential

Save the api_key returned by polling (note: what is saved is api_key, not the short token from Step 2):

python scripts/auth.py save-token {api_key}

Tell the user that login is successful and they can start using the scan code book feature.

Token Usage

Include the Header in all subsequent API calls:

Authorization: Bearer {token}

API base URL:https://data.cli.im/x-deepscan

Error Handling

• Network error: Prompt the user to check the network and retry.
• QR code expired: Re-execute Step 2.
• Token invalid(API returns 401): delete the local token and log in again.

python -c "import os; p=os.path.expanduser('~/.deepscan/token'); os.remove(p) if os.path.exists(p) else None"