Management API

Workspace key lifecycle

These operations apply to personal and organization workspaces. The credential creator must remain an owner or admin of that workspace; no Netra platform-admin role is needed. Existing credentials receive no new mutation permissions automatically. Issue a new credential with the required permissions.

• GET /v1/management/api-keys/{keyid}: configuration and lifecycle status (Observe).
• GET /v1/management/api-keys/{keyid}/usage: lifetime and allowance usage, including revoked keys (Observe).
• PATCH /v1/management/api-keys/{keyid}/limits: update supplied limits (Update limits).
• POST /v1/management/api-keys/{keyid}/allowance: add to a finite cap (Update limits).
• POST /v1/management/api-keys/{keyid}/reset-usage: reset allowance consumption (Reset allowance; also Update limits when replacing a cap).
• POST /v1/management/api-keys/{keyid}/regenerate: replace a secret while retaining keyid (Regenerate).

Token budgets and renewal

{"name":"Member subscription","request_id":"00000000-0000-4000-8000-000000000001","budget_mode":"tokens","monthly_token_budget":1000000,"token_budget_scope":"all","budget_period":"fixed"}

Create and update support rpm_limit, tpm_limit, monthly_budget_micros, budget_mode (credit/tokens), monthly_token_budget, token_budget_scope (all/input/output), and budget_period (monthly/fixed). Fixed has no automatic renewal and initially counts historical usage. All counts input plus output with cached input included once. There is one cap per key. Token caps are positive safe integers or null for unlimited. Omitted fields remain unchanged on update; switching mode clears the other budget unit.

{"request_id":"00000000-0000-4000-8000-000000000002","monthly_token_budget":1000000}

Send this to reset-usage to start a fresh allowance and replace its cap atomically; omit the cap to retain it. Reset changes allowance consumption only. Lifetime usage, billing records, organization spending, wallet movements, pricing, and postpaid charges remain unchanged. Outstanding holds survive. In-flight and delayed settlement still counts; requests crossing a UTC month boundary retain their original admission month. Reset does not reactivate revoked or expired keys.

To add quota while retaining unused allowance, send request_id and a positive amount to allowance. The unit is tokens in token mode or USD micro-units in credit mode. This increments a finite cap atomically; it does not add wallet credit or change an invoice.

Rotation and retries

Regenerate accepts request_id and returns key once, preserving keyid, expiry, limits, ownership, baseline, and history. New requests with the old secret fail after rotation. Existing authorization watchers may terminate in-flight work; recorded consumption still settles. Reset, allowance addition, and regeneration require request_id. Creation supports it for safe retries. Reuse the same UUID and arguments on retry. A replay never repeats the mutation or reveals a secret; conflicting reuse returns 409. If a secret is lost, regenerate using a new request_id.

Usage and reconciliation

lifetime contains durable settled token counters. reported_lifetime uses the existing reporting reader and includes cached_tokens and as_of; reporting can lag settlement. allowance contains cap, used, reserved, remaining, unit, status, and reset_at. Amounts are decimal strings; null cap/remaining means unlimited. Existing GET /v1/usage remains a lifetime read using the inference key.

For monthly reconciliation, exchange CSV fields organization_id, keyid, subscription_reference, period_start_utc, period_end_utc, input_tokens, output_tokens, cached_input_tokens, billed_cost_nanos. Use half-open UTC periods and full keyid, never secrets or three-character prefixes. Match original settled ledger charges, not current prices or allowance counters. Subscription references belong to the integrating organization. This is a reconciliation convention, not an automatic invoice/export feature.

Signed key event webhooks

PUT /v1/management/api-keys/webhook with a url requires Manage webhooks. The URL must use public HTTPS on port 443; redirects and private addresses are blocked. The response returns signing_secret once; another PUT replaces it. GET reads configuration without the secret. DELETE disables delivery.

Events contain id, type, org_id, keyid, created_at and data, never API secrets. They cover lifecycle operations and key status changes, including dashboard revocation. Verify X-Netra-Signature as v1=hex(HMAC-SHA256(signing_secret, X-Netra-Timestamp + "." + raw_request_body)); reject stale timestamps and deduplicate X-Netra-Event-ID. Delivery is at least once, with up to 12 attempts and exponential retry capped at one hour. Return 2xx to acknowledge. Events queue only while subscribed. Expiry and allowance exhaustion remain polling states, not threshold notifications.

Management credentials

Personal workspace owners and organization owners/admins can choose Management in the Create API key dialog. Both personal and organization workspaces support the full management API, including key usage, limits, regeneration, allowance resets, and webhooks. Management keys have a name and optional expiration, and always include Observe API keys. Select Create, Revoke, Update limits, Regenerate, Reset allowance, and Manage webhooks independently; Observe is always included.

Management keys appear in a separate table on the same page, hidden until at least one exists. Revoke them there at any time. Their mk_live_ credentials cannot call inference or MCP. They operate only on inference keys in their own workspace; creating or revoking other management keys requires the dashboard. Removing the creator's owner/admin access also disables their management keys.

Endpoints and permissions

Use Authorization: Bearer <MANAGEMENT_KEY> with these endpoints:

List inference keys

GET returns data, limit, and offset. Advance offset by the number of rows received until data is empty. Results include revoked and expired inference keys, identifying metadata and configured limits, never stored secrets. The maximum page size is 100.

curl "https://api.netra.sh/v1/management/api-keys?limit=100&offset=0" \
  -H "Authorization: Bearer $NETRA_MANAGEMENT_KEY"

Create an inference key

POST accepts a name (1-100 characters) and optional expires_in_days: null for no expiration, or 1, 7, 14, 30, 60, or 90. Creation also accepts the budget and rate-limit fields described above. Omitted per-key caps default to unlimited; organization limits and billing still apply. The successful HTTP 201 response contains the full inference key exactly once. The request body is:

{"name":"Production integration","expires_in_days":30}

curl https://api.netra.sh/v1/management/api-keys \
  -H "Authorization: Bearer $NETRA_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production integration","expires_in_days":30}'

Revoke an inference key

DELETE returns the inference key's keyid and revoked status. Repeating a revoke succeeds without restoring access. Unknown or foreign-workspace keys return 404. Invalid, expired, revoked, or no-longer-authorized management credentials return 401; missing Create/Revoke permission returns 403. Responses use Cache-Control: no-store.

curl -X DELETE "https://api.netra.sh/v1/management/api-keys/$NETRA_KEY_ID" \
  -H "Authorization: Bearer $NETRA_MANAGEMENT_KEY"

Use the inference key identifier from the list response for NETRA_KEY_ID. Invalid bodies or pagination return 400; unsupported methods return 405; temporary management-service failures return 503. Retry with the same request_id and arguments. Without request_id, legacy creation is not idempotent: inspect the list before retrying.

Read usage by key identifier

Every response carries the inference key's keyid: a 16-character public handle, never the secret. Record it when you create or list a key, then read that key's usage at any time without holding the inference secret. Revoked and expired keys remain readable, so this covers post-mortems and month-end reconciliation.

curl https://api.netra.sh/v1/management/api-keys/4c8e0b91a2f7d635/usage \
  -H "Authorization: Bearer $NETRA_MANAGEMENT_KEY"

{
  "keyid": "4c8e0b91a2f7d635",
  "as_of": "2026-11-12T09:05:31.442Z",
  "budget_mode": "credit",
  "budget_period": "monthly",
  "token_budget_scope": "all",
  "reported_lifetime": {
    "input_tokens": "184320",
    "output_tokens": "51200",
    "cached_tokens": "0",
    "total_tokens": "235520",
    "as_of": "2026-11-12T09:05:31.442Z"
  },
  "lifetime": {
    "input_tokens": "184320",
    "output_tokens": "51200",
    "total_tokens": "235520"
  },
  "allowance": {
    "unit": "usd_nanos",
    "cap": "2000000000000",
    "used": "173500000",
    "reserved": "0",
    "remaining": "1999826500000",
    "status": "available",
    "reset_at": null
  }
}

Requesting GET /v1/management/api-keys/{keyid} returns the same configuration fields without lifetime or allowance. Both reads accept no query parameters: an unknown key or one from another organization returns 404, a management key without Observe returns 403, and inactive credentials return 401. The API key usage guide explains the fields, and GET /v1/usage remains the self-read for an inference key.