Skip to main content

​
API Keys, Usage, and Billing Helpers

This page documents workspace-level API-key management and lightweight usage/billing helper endpoints.

​
Endpoints

​
API key lifecycle

  • GET /api/workspaces/:workspaceId/api-keys
  • POST /api/workspaces/:workspaceId/api-keys
  • PUT /api/workspaces/:workspaceId/api-keys/:keyId
  • DELETE /api/workspaces/:workspaceId/api-keys/:keyId

​
Workspace helper reads

  • GET /api/workspaces/:workspaceId/usage
  • GET /api/workspaces/:workspaceId/billing

​
Auth, scopes, and feature gates

  • API-key lifecycle routes are session-only and reject API-key auth.
  • Permission family:
    • api_keys:read, api_keys:create, api_keys:update, api_keys:delete
  • API key creation/update/delete require API-access entitlement (apiAccess feature).
  • Helper reads require billing:read.

​
Create API key payload

POST /api/workspaces/:workspaceId/api-keys 
{
  "name": "CI integration",
  "scopes": ["links:read", "links:create"],
  "rateLimit": 1200,
  "expiresAt": "2026-12-31T23:59:59.000Z"
}
Behavior:
  • name is required.
  • scopes defaults to link CRUD scopes if omitted.
  • Invalid scopes return INVALID_SCOPES.
  • rateLimit is clamped to 100..10000.
  • expiresAt must be valid ISO date string if provided.
  • Plan limits are enforced before creation.
  • Concurrent create requests can return 409 CONCURRENT_REQUEST.
Response note:
  • Plain API key value is returned only on creation.

​
Update API key payload

PUT /api/workspaces/:workspaceId/api-keys/:keyId 
{
  "name": "CI integration (rotated)",
  "enabled": true,
  "rateLimit": 2000
}
Updatable fields:
  • name
  • enabled
  • rateLimit

​
Usage helper response shape

GET /api/workspaces/:workspaceId/usage returns:
  • usage: links, rules, domains, campaigns, pixels, apiKeys, clicks
  • limits: current plan limits
  • credits: balance/included/used cycle micros
  • plan: plan tier

​
Billing helper response shape

GET /api/workspaces/:workspaceId/billing is a compatibility helper that returns workspace plan and basic billing fields. Use /api/billing/* routes for full subscription lifecycle, credit purchases, auto-recharge, and invoice history.

​
Common errors

  • 400: invalid name/scopes/rateLimit/expiresAt
  • 403: missing permission or feature gate, plan limit exceeded
  • 404: API key/workspace not found
  • 409: concurrent create lock or state conflict