Management API
The management API is the control plane this console talks to: workspaces, inference keys, usage and activity. A management key lets a script or an agent platform call it without a browser session.
Authenticating
Management calls sit under /mgmt/v1 and carry the key as a bearer token. The secret is shown once, when it is created or rotated: store it, because only a hash is kept and a lost secret can be replaced but not recovered. New keys start with th-admin-; keys created earlier start with thm-live- and keep working.
curl https://tokenhub-api.belive.sg/mgmt/v1/workspaces \ -H "Authorization: Bearer th-admin-…"
Create, rotate and revoke keys under API Keys → Management keys. A rotation takes an overlap_seconds from 0 to 86400: the old secret keeps working for that long beside the new one, so a deployment can pick the new secret up before the old one stops. A revoked or expired key answers 401 with metadata.reason set to revoked, expired or unknown_key, and an invalid bearer token never falls back to a browser session.
A management key is not an inference key. It cannot call /api/v1, and an inference key cannot call /mgmt/v1.
Scopes
A key carries one or more of eight scopes. There is no wildcard: a call outside the key’s scopes is 403 permission_denied, with the missing scope in metadata.required_scope.
| Scope | What it grants |
|---|---|
workspaces:read | List workspaces and read their routing defaults. |
workspaces:write | Create workspaces and update a workspace's rate_limit_rpm. Routing defaults, the default model and the monthly budget remain signed-in session settings. |
keys:read | List inference keys with their monthly caps. |
keys:write | Create, update and revoke inference keys — within the key’s own ceiling, which is the highest monthly cap it may set. |
usage:read | Read and export aggregated usage: GET /mgmt/v1/usage. |
logs:read | Read and export per-request activity metadata: GET /mgmt/v1/activity. |
catalog:read | Read the model catalogue, its endpoints and its prices. |
audit:read | Read the organization’s audit log: GET /mgmt/v1/audit. Organization-wide only, because the audit log is the organization’s and there is nothing for an allow-list to narrow. Minting a key with both is refused with 422 audit_requires_org_scope; a key that has both is answered 403 permission_denied with that reason. |
A key may also be limited to named workspaces, and to a maximum and a default monthly cap for the inference keys it creates. Both caps are decimal USD strings, and the default may not be higher than the maximum.
What a management key may never do
- Mint or rotate another management key. There is no scope for it. New keys and rotations come from a signed-in admin in this console, so a leaked key cannot extend itself. A key may inspect (
GET /mgmt/v1/management-keys/self) and retire (POST /mgmt/v1/management-keys/self/revoke) only the credential it presents. - Touch
/mgmt/v1/auth. Sign-up, sign-in, email verification and password reset are session routes for people. A management key cannot create an account, read one, or start a password reset. - Call the data plane. Completions on
/api/v1need an inference key. A management key withkeys:writecan create one, which is the audited path. - Reach the operator plane.
/admin/v1belongs to BeLive staff and takes an operator token issued out of band. No tenant credential opens it. - Change BYOK credentials, presets, routing policy or billing. The contract gives management keys no operation for any of them: they stay with a signed-in admin in this release.
Workspace scope and session-only operations
An unknown, foreign or excluded workspace returns 404. A valid management key reaching an accessible operation that requires a person returns 403 with metadata.reason: session_only. Use a signed-in owner/admin for those settings; changing a key scope cannot turn a management key into a session.
Exporting usage and activity
GET /mgmt/v1/usage (scope usage:read) and GET /mgmt/v1/activity (scope logs:read) return one bounded page per call, as JSON or CSV. The window [from, to) is half-open and UTC.
| Parameter | Where | Value |
|---|---|---|
from, to | both, required | RFC 3339 instants. Usage: at most 31 days, or 366 for month buckets, and the first bucket may be partial. Activity: any finite window. |
bucket | usage, required | day or month. |
group_by | usage, required | workspace, key, model or provider or source (model, API or Tool activity). |
workspace_id, api_key_id, model_id, provider | both | Filters. Each may appear once, and never empty. |
http_status | activity | Any status from 100 to 599. |
failure_only | activity | true returns only failed requests (status 400 or above). |
limit | both | 1–200 rows, 50 by default. |
format | both | json (default) or csv. Both use the same page boundary. |
cursor | both | The previous page’s next_cursor, echoed in the X-Next-Cursor header beside X-Has-More. It binds every parameter, so a page cannot be replayed under different filters. |
curl -G https://tokenhub-api.belive.sg/mgmt/v1/usage \ -H "Authorization: Bearer th-admin-…" \ -d from=2026-09-01T00:00:00Z -d to=2026-10-01T00:00:00Z \ -d bucket=day -d group_by=model -d format=csv bucket_start,group_by,group_key,requests,known_prompt_tokens,known_completion_tokens,known_cached_read_tokens,unknown_base_usage_requests,unknown_cache_usage_requests,cost_usd,platform_billed_usd,upstream_billed_estimate_usd,unpriced_requests,unknown_cost_requests 2026-09-01T00:00:00Z,model,deepseek/deepseek-v4-pro,1420,2210480,318920,0,0,0,6.8360,6.8360,6.8360,0,0
Money is a decimal string in USD, not a number, so read it with a decimal type. A page larger than 1 MiB is refused with 413 and no cursor advance: ask for a smaller limit or a shorter window. The X-Export-Schema response header names the column set (usage v1, activity v2), so a parser can pin the shape it was written for. The activity CSV has one row per request, with its model, provider, status, tokens, cost_status, cost_usd, platform_fee_usd, credential_source and error. What the money columns mean is on the Cost page.