API Keys

API keys provide authentication for non-browser clients such as the VSCode extension, CLI tools, and programmatic integrations. Keys use the inf_ prefix for easy identification and are stored as SHA-256 hashes in Firestore with a Redis cache layer.

Key properties:

• Prefix: inf_ followed by URL-safe base64 characters

• Storage: SHA-256 hashed in Firestore (raw key is never stored)

• Cache: Redis-cached verification with a 15-minute TTL

• Expiry: Keys expire after 90 days of inactivity

---

POST /api-keys

Create a new API key. The raw key is returned exactly once in the response and cannot be retrieved again.

POST /api-keys

Authentication

Requires Firebase Auth (Authorization + X-Firebase-AppCheck headers). API key creation is only available to authenticated web users.

Request Body

Parameter	Type	Required	Default	Description
name	string	No	"Default"	A human-readable label for identifying the key.

Request Example

curl -X POST https://inference-api-611798501438.us-central1.run.app/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "X-Firebase-AppCheck: <app_check_token>" \
  -d '{
    "name": "VSCode Extension"
  }'

Response

{
  "key_id": "k_abc123def456",
  "api_key": "inf_dGhpcyBpcyBhIHNhbXBsZSBrZXk...",
  "name": "VSCode Extension",
  "created_at": "2026-02-25T10:00:00Z",
  "expires_at": "2026-05-26T10:00:00Z"
}

Important: Copy the api_key value immediately. It is displayed only once and cannot be retrieved after this response.

Response Fields

Field	Type	Description
key_id	string	Unique identifier for managing the key (list, revoke).
api_key	string	The full API key. Use this value in X-Api-Key headers. Shown only once.
name	string	The label assigned to this key.
created_at	string	ISO 8601 timestamp of key creation.
expires_at	string	ISO 8601 timestamp of key expiration (90 days from creation).

Error Responses

Status	Description
401	Missing or invalid Firebase authentication
429	Maximum number of active keys reached
500	Internal server error

---

GET /api-keys

List all API keys for the authenticated user. The raw key values are never returned; only the prefix and metadata are included.

GET /api-keys

Authentication

Requires Firebase Auth (Authorization + X-Firebase-AppCheck headers).

Parameters

This endpoint takes no parameters.

Request Example

curl -X GET https://inference-api-611798501438.us-central1.run.app/api-keys \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "X-Firebase-AppCheck: <app_check_token>"

Response

{
  "keys": [
    {
      "key_id": "k_abc123def456",
      "name": "VSCode Extension",
      "prefix": "inf_dGhp...",
      "created_at": "2026-02-25T10:00:00Z",
      "last_used_at": "2026-02-25T14:32:00Z",
      "expires_at": "2026-05-26T10:00:00Z",
      "disabled": false
    },
    {
      "key_id": "k_ghi789jkl012",
      "name": "CI Pipeline",
      "prefix": "inf_Y2kg...",
      "created_at": "2026-01-15T08:00:00Z",
      "last_used_at": null,
      "expires_at": "2026-04-15T08:00:00Z",
      "disabled": false
    }
  ]
}

Key List Object

Field	Type	Description
key_id	string	Unique identifier for the key.
name	string	Human-readable label.
prefix	string	First characters of the key for identification (e.g., inf_dGhp...).
created_at	string	ISO 8601 timestamp of creation.
last_used_at	string or null	ISO 8601 timestamp of the most recent use, or null if never used.
expires_at	string	ISO 8601 timestamp of key expiration.
disabled	boolean	Whether the key has been revoked.

Error Responses

Status	Description
401	Missing or invalid Firebase authentication
500	Internal server error

---

DELETE /api-keys/{key_id}

Revoke an API key. The key is immediately disabled and removed from the Redis cache. Any in-flight requests using the key will fail on their next authentication check.

DELETE /api-keys/{key_id}

Authentication

Requires Firebase Auth (Authorization + X-Firebase-AppCheck headers).

Path Parameters

Parameter	Type	Required	Description
key_id	string	Yes	The key ID to revoke (from POST /api-keys or GET /api-keys).

Request Example

curl -X DELETE https://inference-api-611798501438.us-central1.run.app/api-keys/k_abc123def456 \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "X-Firebase-AppCheck: <app_check_token>"

Response

{
  "status": "revoked",
  "key_id": "k_abc123def456"
}

Error Responses

Status	Description
401	Missing or invalid Firebase authentication
404	Key not found or does not belong to the authenticated user
500	Internal server error

---

Verification Flow

When an API key is presented in the X-Api-Key header, the backend follows this verification sequence:

1. Redis cache check: Look up the SHA-256 hash of the provided key in Redis. If found and valid, authentication succeeds immediately.

2. Firestore lookup (cache miss only): Query the api_keys collection for a document matching the hash. Verify the key is not disabled or expired.

3. Cache population: On successful Firestore verification, the result is cached in Redis with a 15-minute TTL.

4. User resolution: The key's associated user_id is used to load the user record for credit checks and billing.

This two-tier approach ensures low-latency authentication for active keys while keeping Firestore as the authoritative source of truth.