Management API Keys

Create and manage FreeRouter API keys programmatically — one key per customer, automated rotation, usage-driven revocation. Modelled on OpenRouter's management API keys.

What they are

A management key (fr_mgmt_…) is a workspace-scoped admin credential. It authorizes the key-management API, which lists, creates, updates, and revokes your workspace's FreeRouter inference keys (fr_live_…).

Management keys cannot run inference — presenting one to api.freerouter.com returns 401. Conversely, a FreeRouter API key cannot manage keys — presenting one to the management API returns 401. The two key types live in separate tables and are never interchangeable.

Creating a management API key

Use cases

• SaaS applications — mint a unique FreeRouter key per customer instance.
• Key rotation — regularly rotate inference keys for security compliance.
• Usage monitoring — track keys and revoke ones that exceed your limits.

Base URL & auth

All key-management endpoints live under /api/v1/keys on the app host and take the management key as a Bearer [REDACTED]

https://app.freerouter.com/api/v1/keys

Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY

List keys — GET /api/v1/keys

Returns the workspace's FreeRouter API keys (metadata only — never secrets), most recent 100. Paginate with ?offset=N.

curl https://app.freerouter.com/api/v1/keys \
  -H "Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY"

curl "https://app.freerouter.com/api/v1/keys?offset=100" \
  -H "Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY"

Create a key — POST /api/v1/keys

Body: name (or label) and an optional api_shape (openai default, openrouter, anthropic, google). The new key's secret comes back once as data.key — store it; it is never returned again.

curl https://app.freerouter.com/api/v1/keys \
  -X POST \
  -H "Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Instance Key",
    "api_shape": "openai"
  }'

Get a key — GET /api/v1/keys/:id

curl https://app.freerouter.com/api/v1/keys/KEY_ID \
  -H "Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY"

Update a key — PATCH /api/v1/keys/:id

Rename with name (or label); revoke with revoked: true, restore with revoked: false.

curl https://app.freerouter.com/api/v1/keys/KEY_ID \
  -X PATCH \
  -H "Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Key Name",
    "revoked": false
  }'

Revoke a key — DELETE /api/v1/keys/:id

Revokes the inference key immediately (apps using it stop working). Rows are retained so you keep an audit trail — same as the dashboard's Revoke button.

curl -X DELETE https://app.freerouter.com/api/v1/keys/KEY_ID \
  -H "Authorization: Bearer $FREEROUTER_MANAGEMENT_KEY"

Response format

Responses use the { data: … } envelope with key metadata (no secrets, except key on creation). Errors are { error: message } with standard HTTP statuses (401 bad management key, 404 unknown key id, 400 bad body).

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "label": "Customer Instance Key",
    "key_prefix": "fr_live_abc12345",
    "api_shape": "openai",
    "created_at": "2026-09-03T12:00:00.000Z",
    "last_used_at": null,
    "revoked_at": null,
    "key": "fr_live_... (creation only — store it now)"
  }
}