Each Key contains two values, rotation includes an overlap window, and production requires an IP allowlist. Each has an important integration pitfall.
API Keys and Rotation
One Key, Two Values
When you create a Key, we return two values together:
| Value | Purpose | What we store | If you lose it |
|---|---|---|---|
api_key | Obtain a token (POST /v1/connect/token) | Hash only | Create a replacement Key |
signing_key | Verify request signatures | Plaintext, as required for symmetric signing | Can be retrieved |
⚠ These values are not interchangeable. Using
signing_keyto obtain a token returns 401,indistinguishable from an expired Key. First check which value you are using.
Rotation Includes an Overlap Window
Rotation does not immediately invalidate the old Key. We retain it for an overlap window:
轮换
│
旧 Key ├────────────┤ ← 窗口内仍然可用
新 Key ├──────────────────────►
└── 重叠窗口 ──┘
Why this matters: configuration does not reach every instance of your service at the same millisecond. Without an overlap window, some instances would still send requests with the old Key at rotation time, causing a burst of 401 responses that could look like an outage on our side.
The old Key expires immediately when the window ends. There is no additional grace period.
Environments and IP Allowlists
API Keys do not distinguish sandbox/live. Create your Key in the merchant portal for the relevant environment:
merchant.zinfra.dev/api.zinfra.dev: test (sandbox) environment. IP allowlists are neither required nor checked.merchant.zinfra.vip/api.zinfra.vip: production environment. Creating a Key requires security verification and a nonempty IP allowlist. Only listed source IPs may call the API.
The two environments store data and credentials separately. When switching environments, use credentials created in the destination environment. New and rotated keys no longer include live / test prefixes. Existing keys do not need to be recreated because of this naming change.
Related Endpoints
POST /v1/connect/token— Exchangeapi_keyfor an access token