Version-pinned adapterContract 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
Version-pinned adapter
Field family
one-hub
Authorization
Access token
Capabilities
request-level usage logs · channel metadata · current price records · payment order metadata
Credential boundary
Keep credentials in the local sidecar and strip channel keys. Pin the connector to the deployed one-hub revision.
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 | GET /api/status | Public instance metadata | Read the deployed quota conversion and revision where available. |
| Usage logs | GET /api/log/?log_type=2&page=1&size=100&start_timestamp={unix}&end_timestamp={unix} | Administrator | Pagination is 1-based and uses page/size with data.total_count. Allow 1–5 minutes for asynchronous or batched log writes. |
| Channels | GET /api/channel/?page=1&size=100 | Administrator | Remove every key-bearing field before normalization. |
| Current price records | GET /api/prices?type=db | Deployment-dependent | Persist a versioned local snapshot; the endpoint is current state. |
| Payment orders | GET /api/payment/order?page=1&size=100 | Administrator | Use for gateway-wallet joins only. Processor settlement exports remain the cash source of truth. |
Local request headers (illustrative)
Authorization: Bearer $ONE_HUB_ACCESS_TOKENField 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 | — |
channel_id / channel.name | downstreamUsage[].channelId | — |
metadata.cached_read_tokens / cached_tokens | downstreamUsage[].tokens.cacheRead | — |
metadata.cached_write_tokens | downstreamUsage[].tokens.cacheWrite | — |
metadata.reasoning_tokens | downstreamUsage[].tokens.reasoning | — |
Known limitations
- Log writes may lag, so an incremental cursor at wall-clock now can miss late rows.
- Current prices do not prove the historical rate used for an old request.
- Refund semantics and fields remain release-specific.