Authentication

All /open-api/v1/** APIs use API key authentication. API keys are managed through the web console and cannot be created or changed through the APIs in this documentation.

Get an API key

1. Sign in to the production web console.
2. Open the API key management page.
3. Create an API key and assign a recognizable name and expiration time.
4. Immediately save the complete API key in a secure location. The full value is displayed only once, when creation succeeds.

Environment	Web console	API key management
Production	Open the production console	Manage production API keys

Permission scope

An API key can access only the Open APIs documented here; it cannot access web-console APIs. API keys are general-purpose credentials. Fine-grained API permissions, IP allowlists, and purchase limits cannot currently be assigned to an individual key. Every valid API key can access all enabled Open API capabilities under its account.

Protect every API key as a highest-privilege credential for all enabled Open API capabilities under the account. Creating separate keys for different use cases makes identification, rotation, and revocation easier, but does not reduce the permission scope of an individual key. Purchase quantities, inventory, wallet balances, and other business constraints described in each API article still apply.

IP allowlist

Sign in to the production web console to configure the user-level Open API IP access allowlist. All API keys belonging to the same user share this allowlist; it cannot be configured separately for an individual key.

When the allowlist is disabled, Open API requests are not restricted by source IP. When it is enabled, only requests whose source IPv4 address exactly matches an entry in the allowlist are accepted. A nonmatching source returns business error code 300370. If you receive this code, open the web console and check or update the IP access allowlist. Configuration changes may take up to 30 seconds to take effect, so wait for propagation before testing an updated configuration.

Request header

Send exactly one X-API-Key header with every request:

X-API-Key: <YOUR_API_KEY>

An API key consists of the pt- prefix followed by 43 URL-safe characters, for a total length of 46 characters. Do not pass the API key in the query string, request body, or a cookie.

Authentication failures

When a request reaches the Open API and it produces a normal authentication-failure response, the HTTP status is 200 and the response body code is 400001:

{
  "code": 400001,
  "msg": "Authentication failed.",
  "data": null,
  "next": null
}

For security reasons, the response does not identify the exact failure. Check the key status and expiration time in the web console. If you cannot determine the cause, create a new key and replace the key configured in your application.

Security recommendations

• Store and use API keys only in your server-side application.
• Use a secrets manager or protected environment variable; never commit keys to a source repository.
• Do not print complete request headers in logs.
• You may create separate keys for different use cases to simplify identification and rotation; this does not reduce a key's permission scope.
• If you suspect exposure, revoke the old key immediately and replace it.