Authentication and Calling Conventions

Authentication Method

The Public API uses two-step authentication:

1. First, call the token endpoint with your registered email + API Key
2. Then, use the returned Bearer Token to call business endpoints

Specifically:

1. The Basic Auth username is your registered email
2. The Basic Auth password is the raw API Key value
3. The Token is valid for 7 days by default

Get an Access Token

Endpoint:

POST /v1/oauth2/token

Request example:

curl -X POST "https://api.ipxss.com/v1/oauth2/token" \
  -u "[email protected]:your_api_key"

Response example:

{
  "code": 0,
  "data": {
    "access_token": "your_bearer_token",
    "expires_in": 604800,
    "token_type": "bearer"
  },
  "msg": "success",
  "timestamp": 1747036799
}

Failure example:

{
  "code": 40102,
  "data": null,
  "msg": "invalid username or api key",
  "timestamp": 1747036799
}

How to Call Business Endpoints

Except for the token endpoint, all other endpoints use a Bearer Token:

curl -X POST "https://api.ipxss.com/v1/wallet/balance" \
  -H "Authorization: Bearer your_bearer_token" \
  -H "Content-Type: application/json" \
  -d '{}'

Successful response example:

{
  "code": 0,
  "data": {
    "balance": 125.5
  },
  "msg": "success",
  "timestamp": 1747037000
}

If an endpoint supports form submission, you can also use application/x-www-form-urlencoded; the current backend is compatible with both JSON and form submissions.

Common Field Conventions

The current Public API follows these conventions:

1. ip_type: normal or premium
2. duration: week or month (about 7 or 30 days)
3. region: uses the code:count|code:count format, for example hk:1|us:2; mix packages use MIXISP-<id>:<qty> or MIXIPV4-<id>:<qty>
4. num: must equal the sum of all quantities in region

Time Field Conventions

For consumption logs and whitelist filtering, time fields use the following format:

YYYY-MM-DD HH:MM:SS

Example:

2026-04-08 00:00:00

If the end time is earlier than the start time, the endpoint returns a parameter error immediately.

Response Structure

All endpoints return data in the following structure:

{
  "code": 0,
  "data": {},
  "msg": "success",
  "timestamp": 1747036799
}

Common meanings:

1. code = 0 means success
2. data contains business data
3. msg is the status message
4. timestamp is the server timestamp

Common error scenarios:

1. 40101: Missing authentication information or missing Bearer Token
2. 40102: Invalid Token, expired Token, or incorrect API Key credentials
3. 40103: The API Key has expired, been revoked, or is unavailable
4. 40001: Invalid request parameter format or missing required fields
5. 40002: Business validation failed, such as insufficient balance or a resource not found
6. 50201: Upstream direct procurement failed and the current request did not complete activation
7. 50001: Server-side processing failed, please try again later

Usage Recommendations

1. Cache the Token on the server side to avoid requesting a new one for every call
2. Check balance and quota before batch calls to reduce failed requests
3. When activating or renewing Static ISP resources, it is recommended to keep order-to-resource mapping records in your own business system
4. If you need to integrate multiple product lines, it is recommended to build a unified API Client that reuses Token handling, error handling, and time formatting logic