Docs+
Auth & security
Two auth modes, read-only mode, revocation and write protection.
Updated 2026-10-21
usmart-mcp supports OAuth2 authorization code with PKCE (recommended), or the legacy channel-password sign-in kept for 1.0.x compatibility. Your password is only entered on uSMART's page and never enters the model context.
The two modes
| OAuth2 + PKCE | Channel password | |
|---|---|---|
| Credentials | client_id plus a local session file | Phone, password, channel id and signing key |
| Refresh | refresh_token rotates automatically | In-process cache; re-login on expiry |
| Use when | Recommended; public app is enough | Legacy 1.0.x and channel setups |
| Signing key needed | No | Yes |
The flow
- Call oauth_login — it returns the URL and opens the browser
- Sign in on uSMART and approve
- Call oauth_login_status to collect the code and exchange the token
- The session is written to ~/.usmart/oauth_session.json and refreshed automatically
Read-only mode
With USMART_READONLY=1, place_order and modify_order are not registered at the protocol layer at all — not blocked by a client allowlist, simply absent.
Four protections on writes
- Explicit confirmation: every write must pass confirmed=true
- Board-lot validation: quantities are checked before the order leaves the machine
- Local limits: per-order amount, daily amount and daily order count, enforced before any network call
- Audit and no-retry: writes land in a local JSONL trail; timeouts or auth failures go to a human, never a second attempt
Revoking access
Call oauth_logout, or delete ~/.usmart/oauth_session.json — that is a local sign-out. The remote refresh_token lives for 30 days and cannot be revoked locally.
Any AI can misread your intent. Verify symbol, side, quantity and price before ordering; accepted is not filled.
Stuck?
Send us a screenshot and your client version and we will take a look.