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 web console for the relevant environment.
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.

Do not use a test-environment API key in production or a production API key in the test environment.

Environment	Web console	API key management
Test	Open the test console	Manage test API keys
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.

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.