Service and authentication
Authentication
API key
After you turn on OpenAPI on the NexBrowser → API MCP page, copy the API key that the client generates and persists. The key is stored in the client config under your home directory and survives client restarts; resetting the key invalidates the old one immediately.
Every endpoint except the public GET /health requires the header Authorization: Bearer <api-key>. The Bearer keyword is case-insensitive, and the key itself cannot contain spaces.
curl -H "Authorization: Bearer <API_KEY>" http://127.0.0.1:45536/team/list
The API key can call the local OpenAPI, including paid service endpoints that charge the account balance. Do not share it with unauthorized people or write it into publicly accessible files.
Team context
Forwarded endpoints such as teams, accounts, proxies, window listing, window creation and opening, and all paid service endpoints use the client's current sign-in session. Call GET /team/list first and take data[].id: that is the teamId other endpoints need. When accounts and proxies are saved, the server overrides teamId with the current team, so passing it in the request has no effect.
Without a signed-in user, forwarded endpoints return Backend command requires login token. /health, /user/info, /user/config, and /browser/connection_info only read local state.
Language
Messages generated locally by the client (parameter errors, batch failure reasons, proxy check failures, and so on) are always in Simplified Chinese, regardless of the client's UI language. If the request carries Accept-Language (zh-CN or en-US), it is forwarded to the server unchanged, and server-generated msg values, billing descriptions, and similar text follow that language; without it, zh-CN is used.
Automation client ID
In addition to the standard authentication, /automation/* requires X-Nex-Client-Id. Its value must match [A-Za-z0-9._:-]{8,128}.
Sessions belong to that ID: only the client that created a session can read or write it, and after the signed-in account or team changes, the old session returns UNAUTHORIZED.
Service address and health check
The default service address is http://127.0.0.1:45536, and the service listens on 127.0.0.1 only. If the default port is taken, the client moves on to the next free port; the API MCP page in the client shows the port actually in use.
GET /health is public and does not need the Authorization header:
curl http://127.0.0.1:45536/health
Service endpoints
The Proxy Store (/ip/*), cloud phone numbers (/sms/*), mailbox service (/mail/*), CAPTCHA solving (/captcha/*), and billing transactions (/billing/*) are called service endpoints and follow these extra conventions.
| Convention | Details |
|---|---|
| Strict validation | Non-/sms/* endpoints validate an allowlist; unknown fields or wrong types return code: -1100, with msg listing field: reason. /sms/buy accepts only countryId, projectId, and quantity; extra fields return code: 1 |
| Direct charging | Purchases, renewals, and CAPTCHA task submissions take only business parameters. The server calculates and charges the current price; the client no longer pre-checks prices, stock, or plans. The server validates permission, balance, and availability |
| Context ID | Successful responses carry contextId at the top level of the envelope, identifying the sign-in and team of the request |
| No duplicate unknown charges | Submit each request once. Reconcile unclear outcomes against the matching records and /billing/trades; stop if unresolved. Confirmed business failure may trigger caller-managed replacement within the recovery limit |
Optional request headers:
| Header | Details |
|---|---|
X-Nex-Service-Context | Pass a contextId from an earlier response to pin a multi-step flow to the same sign-in and team; if either has changed, the request returns code: "SESSION_CONTEXT_CHANGED" and does nothing. CAPTCHA automation actions require this header |
X-Nex-Request-Deadline | Request deadline as a millisecond timestamp, which must be a decimal integer; the client shortens its wait on the server accordingly, and batch checks in /proxy/detect are scheduled against it |
curl -X POST http://127.0.0.1:45536/captcha/schema \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-H "Accept-Language: en-US" \
-d '{"productCode":"RECAPTCHA_V2"}'
Paid services needed for an authorized task submit directly, without quotation or separate fee confirmation. maxTotalPrice has been removed: including it or another unknown field in /sms/buy returns code: 1; other purchase and renewal endpoints return code: -1100. Server business errors pass through unchanged. After a purchase network timeout or unclear outcome, reconcile records and billing; stop if unresolved, without duplicate charges. Confirmed business failure or an SMS/email receiving timeout may trigger replacement under the automation rules.
Interactive recovery in the built-in Agent and MCP automation defaults to 120 seconds for SMS, 180 seconds for email and at most 3 attempts per resource flow including the first, without repeated requests for a reply. Country/project and mailbox suffix/type changes must still match the site and required user constraints and do not reset the count. -1208 or insufficient_balance stops subsequent spending and quota consumption. Each HTTP call performs only the requested operation; it does not implicitly run the replacement workflow. nex_service_recovery is a built-in Agent tool, with no public MCP tool or HTTP route. Local MCP mailbox waiting/filtering parameters are not /mail/pull request fields.