Verified read contractContract reviewed: 2026-07-10
Security boundary
PayAPIKey's hosted endpoints do not accept gateway administrator tokens, channel keys, cookies, or sessions. Native API reads must happen in a local connector/sidecar you control; the hosted service receives stripped billing metadata only.
Support scope
Mode
Verified read contract
Field family
one-api-compatible
Authorization
System access token
Capabilities
request-level usage logs · asynchronous-task refund logs · channel metadata · current pricing snapshot · top-up order metadata · optional channel balance refresh
Credential boundary
Keep both values in the local connector or sidecar. The hosted PayAPIKey API never accepts these headers or their values.
Read flow
- 1Run a local connector/sidecar in the gateway network and call the native endpoint with a least-privilege account.
- 2Strip sensitive fields locally and submit only the logs response and connector ID to /api/v1/normalize.
- 3Merge upstream billing and payment-settlement exports, then call /api/v1/reconcile.
Native resources
| Purpose | Method and path | Permission | Notes |
|---|---|---|---|
| Instance status and quota conversion | GET /api/status | Public instance metadata | Read data.quota_per_unit and data.version before converting quota. Never assume 500,000 globally. |
| Usage logs | GET /api/log/?type=2&p=1&page_size=100&start_timestamp={unix}&end_timestamp={unix} | Administrator | Pagination is 1-based and page_size is at most 100. Freeze an end watermark, overlap time windows, and deduplicate event IDs. |
| Refund logs | GET /api/log/?type=6&p=1&page_size=100&start_timestamp={unix}&end_timestamp={unix} | Administrator | Confirmed mainly for asynchronous-task refunds; it is not complete evidence for every synchronous pre-charge reversal. |
| Channels | GET /api/channel/?p=1&page_size=100 | Administrator | Use IDs and names locally. Remove key-bearing fields before sending any payload to PayAPIKey. |
| Current pricing | GET /api/pricing | Deployment-dependent | Current state is not historical evidence. Save a local versioned snapshot with effective time on every collection. |
| Top-up orders | GET /api/user/topup?p=1&page_size=100 | Administrator or authorized user | TopUp.money does not reliably carry currency. Join processor exports locally and never infer a currency. |
| Refresh channel balances | GET /api/channel/update_balance | Administrator | Optional side effect: this triggers provider requests and must not be polled aggressively. |
Local request headers (illustrative)
Authorization: Bearer $NEW_API_ACCESS_TOKEN
New-Api-User: $NEW_API_USER_IDField mapping
Mapping is performed by the connector/sidecar or /api/v1/normalize. A synthetic ID is generated when a historical record has no request_id, but it cannot guarantee request-level upstream matching.
| Source field | Canonical field | Notes |
|---|---|---|
request_id / requestId | downstreamUsage[].requestId | Use the administrator log endpoint where possible. Some self-log views rewrite display IDs. |
created_at | downstreamUsage[].occurredAt | Unix seconds are normalized to an ISO 8601 UTC timestamp. |
user_id / username | downstreamUsage[].userId | — |
token_id / token_name | downstreamUsage[].tokenId | — |
model_name | downstreamUsage[].model | — |
channel / channel_id | downstreamUsage[].channelId | — |
quota | downstreamUsage[].chargedAmount | Downstream billing units only, never provider cost. Divide by the deployed /api/status.data.quota_per_unit value. |
prompt_tokens | downstreamUsage[].tokens.input | — |
completion_tokens | downstreamUsage[].tokens.output | — |
other.cache_tokens / cached_tokens | downstreamUsage[].tokens.cacheRead | — |
other.cache_write_tokens / cache_creation_tokens | downstreamUsage[].tokens.cacheWrite | — |
other.reasoning_tokens | downstreamUsage[].tokens.reasoning | — |
Known limitations
- Gateway quota and channel used_quota represent downstream billing/credit counters, not the provider invoice cost.
- Current pricing endpoints do not reconstruct historical price changes unless snapshots were retained.
- Cache, reasoning, media, and task metadata vary by adaptor and release.
- Payment settlement, fees, refunds, and chargebacks must come from the payment processor export.