> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linquid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys, Usage, and Billing Helpers

> Workspace API-key lifecycle plus workspace-scoped usage and billing helper reads

# 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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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