Aggregate/file importContract 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
Aggregate/file import
Field family
voapi-v2
Authorization
Raw JWT for v2 source APIs
Capabilities
aggregate usage reference · usage CSV import · canonical JSON import · limited key-template pricing context
Credential boundary
VoAPI v2 uses a raw JWT rather than the One API Bearer profile. Keep it local; never send it to PayAPIKey.
Read flow
- 1Use a local connector to read /api/dash/statistics for aggregate checks, or export request-level billing records for the settlement period.
- 2Remove keys, cookies, sessions, prompts, and completion content; keep billing fields only.
- 3Import CSV/JSON by downstream, upstream, and payment ledger in the browser workbench, or convert to canonical JSON and call /api/v1/reconcile.
Native resources
| Purpose | Method and path | Permission | Notes |
|---|---|---|---|
| User and deployment context | GET /api/user/info | Authorized user | VoAPI v2 envelope uses {code,data,msg,rid}. |
| Aggregate dashboard statistics | GET /api/dash/statistics | Authorized user | Aggregate-only evidence. It cannot support Request ID matching or request-level leak conclusions. |
| Key template context | GET /api/keys/template | Authorized user | Provides limited group/multiplier context, not full historical pricing. |
Local request headers (illustrative)
Authorization: $VOAPI_JWTField 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 |
|---|---|---|
statistics interval | period.start / period.end | VoAPI v2 exposes an aggregate interval, not a request timestamp. |
usedBasicBalance + usedBindBalance | aggregate downstream consumption | Aggregate-only reference. Convert to canonical request rows locally only when a reliable source export exists. |
key template group | pricing metadata | Provides limited group/multiplier context, not a historical price snapshot. |
Known limitations
- The verified v2 API is aggregate-only for usage; request IDs, models, channels, and token classes are not available for exact reconciliation.
- Do not treat VoAPI v2 as the legacy One/New API protocol; authentication and response envelopes differ.
- Use sanitized canonical CSV/JSON for request-level reconciliation until a versioned export contract is available.
Bottom line: VoAPI v2 supports caller-operated aggregate reads; Request ID-level reconciliation currently requires canonical CSV/JSON file import.