If you will check a balance, place an order, or extract a residential proxy through the API, sign in first, then send the access token on later calls. The official Authentication docs say the public APIs use JWT Bearer tokens: call the login endpoint with a username and password, then send the returned token on authenticated requests. This page covers login, sending the token, and the auth errors already listed in the docs. For what the API can do overall, see API integration. This is not a reprint of the OpenAPI.
Buyers who only use the console do not have to call the login API. This page is for integrations that need balance, billing records, dynamic traffic purchases, or static IP orders. Authorized targets only. Not supported in mainland China.
What to prepare
| Item | Where it comes from |
|---|---|
| Console username and password | Your own credentials; samples use only USER_EXAMPLE and PASS_EXAMPLE_NOT_REAL |
| API base URL | Documented as https://backend.ztproxy.net/api for all users |
| A place to store the token | A server-side secret store, not frontend code or logs |
Usernames, passwords, and JWT fragments in official samples are not your live account. This page uses fake placeholders only. When you warn about credential formatting, say the username and password as separate fields, never credentials@host.
How to send the token after login
A successful login uses code: 0 in the documented example. data.token is what you send later. data.user may include an id, username, balance, and status; those figures are documentation samples, not a live account. On authenticated calls, send:
Authorization: Bearer <token>
Replace <token> with the value you just received. Do not attach the password again on those later calls. One documented follow-up example is the dashboard overview. If the token is invalid or expired, sign in again instead of retrying order parameters.
Login example
export ZTPROXY_BASE="https://backend.ztproxy.net/api"
curl -X POST "$ZTPROXY_BASE/auth/login" \
-H "Content-Type: application/json" \
-d '{
"username": "USER_EXAMPLE",
"password": "PASS_EXAMPLE_NOT_REAL"
}'After a successful response, store the token as an environment variable such as ZTPROXY_TOKEN=TOKEN_EXAMPLE_NOT_REAL, then send Authorization: Bearer $ZTPROXY_TOKEN on later requests. Do not paste a live token into tickets, screenshots, or a client repository. The Chinese source of record is 认证; both language pages describe the same fields, and you should read error wording from the language page you are following.
| Practice | Meaning |
|---|---|
Send the token in the Authorization: Bearer header | This is the documented usage |
| Put the token or password in frontend code, logs, screenshots, or tickets | Do not do this |
| You receive 401 because the token is invalid or expired | Sign in again, then retry once; do not loop retries without a new token |
Documented auth errors
Handle only the errors listed on the official authentication page. This article does not dump the full error catalog. Broader business errors are in Error handling. Client 407 or timeout issues are in connection troubleshooting.
| HTTP | Documented message | What it means |
|---|---|---|
| 401 | Authentication token missing | No Authorization header; add a Bearer token |
| 401 | Invalid authentication token | The token is invalid or expired; sign in again, then retry once |
| 401 | User not found | The user bound to the token no longer exists; stop using that token |
| 403 | Account not activated | The account exists but is not activated; complete the email activation first |
The Chinese authentication page uses the corresponding messages 「未提供认证令牌」, 「无效的认证令牌」, 「用户不存在」, and 「账号未激活，请先前往邮箱点击激活链接」. These auth errors are not the same thing as a 407 from a target site.
Compliance and scope
Store credentials and tokens on a server or in a secrets manager. Do not embed them in client code or logs. Authorized targets only. Prices follow the console and Pricing (dynamic about $0.40/GB, about $0.20/GB for the 100 TB package; static shared about $1.50 and exclusive about $5 per IP per month). USDT/USDC are available; Visa/Mastercard are still being applied for. Not supported in mainland China.
FAQ
Do I have to call login before a console purchase?
Not necessarily. The console already signs you in. This page is for official API integrations. Console purchases and API orders can share the same processing path, but a buyer working in the console does not need to attach a token by hand.
Should the token go in the header or the URL?
Use the Authorization: Bearer header. Do not put the token in the query string or in frontend code.
Is a failed login also a 401 about email or password?
The authentication page lists missing token, invalid token, user not found, and account not activated. The error-handling docs also mention a login failure message about email or password. Check the username and password first; do not treat that case as an expired token.
Can I retry the same request after a 401?
If the token is missing or invalid, add it or sign in again, then retry once. If the user no longer exists, a new attempt with the same token will not work. Do not loop retries without a fresh token.
What should I do with a 403 for an inactive account?
Follow the docs and use the email activation link, then sign in again. This is not a downstream-user permission error.
Is this IP-allowlist authentication?
No. This page is account login with a Bearer token. Proxy connections still use the host, port, username, and password returned by extract or the order, filled in as separate fields; see extract credentials.
Can I reconcile from the balance field in the login response?
If a balance appears in the login payload, it is only a sample-style field from that moment. Reconcile with the balance API and billing records.
May I give the token to an end user?
The docs say not to expose the username, password, or token to end users, and not to write them into frontend code or logs. Keep them on your backend or in a secret store.
Next steps
- Sign in, then store the token safely.
- Call a read-only endpoint first, such as checking the balance.
- Then look up products or place an order.