Feature Request: Admin API for API Key Management with Key-Bound Tags

Summary

We'd like to request two closely related features:

1. A programmatic Admin API for creating, listing, updating, and revoking TensorZero API keys
2. Key-bound tags (metadata) that are automatically injected into every inference made with that key and persisted to ClickHouse

Motivation

We are building a multi-tenant LLM platform where customers provision API keys through our self-service portal. Currently, TensorZero only supports key management via the UI (/api-keys) and the CLI (--create-api-key / --disable-api-key). Neither can be integrated into an external application programmatically.

Beyond key lifecycle management, we need a reliable way to associate billing metadata (e.g. customer ID, project ID, cost center) with every inference. Today, this can be done by having clients pass tensorzero::tags at request time, but this has a fundamental trust problem: any client can set arbitrary tags, including another customer's identity. For billing and compliance, this is not acceptable.

Key-bound tags solve both problems at once: metadata is attached to the key by an admin, the gateway injects it server-side, and the client cannot override it.

Proposed Functionality

1. Admin API for API Key Management

A set of authenticated HTTP endpoints for programmatic key lifecycle management:

The admin API itself should require elevated authentication (e.g. a dedicated admin key, or a scope/role on existing keys).

Example — creating a key with tags:

curl -X POST https://gateway:3000/admin/api-keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": {
      "customer_id": "acme-corp",
      "project_id": "proj-a1b2c3",
      "billing_tier": "premium"
    },
    "expiration": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "api_key": "sk-t0-xxxxxxxxxxxx-yyyy...",
  "public_id": "xxxxxxxxxxxx",
  "tags": {
    "customer_id": "acme-corp",
    "project_id": "proj-a1b2c3",
    "billing_tier": "premium"
  },
  "expiration": "2026-12-31T23:59:59Z",
  "created_at": "2026-03-18T17:00:00Z"
}

2. Key-Bound Tags

Tags attached to an API key should be:

• Automatically injected into every inference and feedback request made with that key
• Persisted to ClickHouse (in the tags map on ChatInference / JsonInference / ModelInference) alongside any client-provided tags
• Authoritative — if a client sends a tag with the same key as a key-bound tag, the key-bound value should take precedence (or the request should be rejected), preventing clients from spoofing their identity
• Usable as rate limiting scopes — so that rate limiting rules can reference key-bound tags without relying on clients to send them correctly

This effectively turns API keys from simple auth tokens into tenant-scoped identity tokens.

Use Case: Multi-Tenant Billing

Our platform runs on OpenStack with self-hosted LLMs (vLLM, sglang on GPU nodes). TensorZero serves as the central LLM gateway. Each customer gets their own API key through our portal. We need to:

1. Create keys programmatically when a customer signs up or requests a new key
2. Attach OpenStack metadata (project_id, domain_id) to each key so we can correlate LLM usage with our existing billing pipeline
3. Query ClickHouse for billing by grouping on these tags — without relying on the client to send them
4. Enforce per-customer rate limits scoped by key-bound tags

Today, we work around this by querying on tensorzero::api_key_public_id and maintaining an external mapping table. Key-bound tags would eliminate this indirection entirely.

Additional Considerations

• Key rotation: It would be useful to rotate the secret portion of a key while preserving the public ID and all associated tags/metadata. This allows credential rotation without disrupting billing continuity.
• Tag namespacing: Consider a prefix convention (e.g. admin:: or key::) to clearly distinguish key-bound tags from client-provided tags in ClickHouse queries.
• Migration path: The tensorzero::api_key_public_id tag that is already auto-injected today is conceptually the same mechanism — key-bound tags would generalize this pattern.
• UI integration: The TensorZero UI should also use the Admin API for key management (aligning with the direction in Make UI fully standalone #5062).

Context

We've been following the progress on making the UI standalone (#5062) and the migration of direct database queries to gateway API endpoints. This feature request aligns with that direction — the Admin API would be another gateway endpoint that both the UI and external systems can consume.

Thank you for building TensorZero — the architecture and performance are excellent, and these additions would make it even more compelling for multi-tenant production deployments.