SuperCompress API Key Management and Usage Endpoints

The key management endpoints let you create and administer the API keys used to authenticate calls to /v1/compress. All six endpoints require a Firebase ID token — not an API key — because they operate on behalf of a signed-in user and are the same routes the dashboard UI calls.

Authentication

All requests on this page must include:

Authorization: Bearer <firebase_id_token>

In dev mode (SC_AUTH_DEV=1) you can pass a synthetic token such as dev:my-uid:me@dev.local instead of a real Firebase token.

GET /api/me

Returns the Firebase uid and email address for the currently authenticated user. This is a lightweight liveness check for the auth layer and is also used by the dashboard on first load.

Example request

curl https://your-api-host/api/me \
  -H "Authorization: Bearer <firebase_id_token>"

Response fields

string

The Firebase user ID.

string

The email address associated with the Firebase account. May be null for anonymous or OAuth-only accounts.

Example response

{
  "uid": "Xk9mR3pLqZVt2nOeD7cF",
  "email": "alice@example.com"
}

GET /api/keys

Lists all active (non-revoked) API keys for the authenticated user, together with a per-key usage summary.

Example request

curl https://your-api-host/api/keys \
  -H "Authorization: Bearer <firebase_id_token>"

Example response

{
  "keys": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Production",
      "prefix": "sc_live_aBcDeFgH",
      "created_at": "2024-11-01T10:00:00+00:00",
      "last_used_at": "2024-11-15T14:32:01+00:00",
      "revoked": false
    }
  ],
  "usage": {
    "3fa85f64-5717-4562-b3fc-2c963f66afa6": {
      "total_requests": 142,
      "total_tokens_in": 589000,
      "total_tokens_out": 206150,
      "total_tokens_saved": 382850,
      "by_day": {
        "2024-11-15": {
          "key_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "requests": 12,
          "tokens_in": 49200,
          "tokens_out": 17220,
          "tokens_saved": 31980
        }
      }
    }
  }
}

POST /api/keys

Creates a new API key for the authenticated user. Returns the key record and the full secret value. The secret is derived from a cryptographically random 24-byte token and is shown only once — it is not stored, only its SHA-256 hash is.

Body parameters

string

default:"Production"

A human-readable label for the key. Maximum 80 characters. Whitespace-only names are stored as "Untitled key".

Example request

curl -X POST https://your-api-host/api/keys \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production"}'

Example response

{
  "key": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Production",
    "prefix": "sc_live_aBcDeFgH",
    "created_at": "2024-11-15T09:00:00+00:00",
    "last_used_at": null,
    "revoked": false
  },
  "secret": "sc_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"
}

The secret field contains the full sc_live_… key and is returned exactly once. Copy it to a secrets manager immediately. If you lose it, you must create a replacement key and revoke the old one.

PATCH /api/keys/

Renames an existing key. Only the display name is changed; the key secret, prefix, and usage history are unaffected.

Path parameter

Parameter	Type	Description
`key_id`	string	UUID of the API key

Body parameters

string

required

New display name. Between 1 and 80 characters. Whitespace-only values are ignored and the existing name is preserved.

Example request

curl -X PATCH https://your-api-host/api/keys/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging"}'

Example response

{
  "key": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Staging",
    "prefix": "sc_live_aBcDeFgH",
    "created_at": "2024-11-15T09:00:00+00:00",
    "last_used_at": "2024-11-15T14:32:01+00:00",
    "revoked": false
  }
}

Returns 404 if the key does not exist or does not belong to the authenticated user.

DELETE /api/keys/

Permanently revokes an API key. The key is immediately removed from the hash lookup index, so any in-flight requests using it will start failing with 401 within milliseconds.

Path parameter

Parameter	Type	Description
`key_id`	string	UUID of the API key

Example request

curl -X DELETE https://your-api-host/api/keys/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer <firebase_id_token>"

Example response

{
  "key": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Production",
    "prefix": "sc_live_aBcDeFgH",
    "created_at": "2024-11-15T09:00:00+00:00",
    "last_used_at": "2024-11-15T14:32:01+00:00",
    "revoked": true
  }
}

Revocation is permanent and immediate. The key hash is removed from the lookup index, and the key record is marked "revoked": true. There is no undo — create a new key if access needs to be restored.

Returns 404 if the key does not exist or does not belong to the authenticated user.

GET /api/keys//usage

Returns a usage snapshot for a single key, broken down by calendar day (UTC).

Path parameter

Parameter	Type	Description
`key_id`	string	UUID of the API key

Example request

curl https://your-api-host/api/keys/3fa85f64-5717-4562-b3fc-2c963f66afa6/usage \
  -H "Authorization: Bearer <firebase_id_token>"

Response fields

integer

Total number of successful /v1/compress calls made with this key.

integer

Cumulative input token count across all requests (tokens before compression).

integer

Cumulative output token count across all requests (tokens after compression).

integer

Cumulative tokens saved: total_tokens_in − total_tokens_out. This directly maps to KV-cache reduction.

object

A map from UTC date strings ("YYYY-MM-DD") to per-day usage records. Each record contains key_id, requests, tokens_in, tokens_out, and tokens_saved for that day.

Example response

{
  "total_requests": 142,
  "total_tokens_in": 589000,
  "total_tokens_out": 206150,
  "total_tokens_saved": 382850,
  "by_day": {
    "2024-11-14": {
      "key_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "requests": 130,
      "tokens_in": 539800,
      "tokens_out": 188930,
      "tokens_saved": 350870
    },
    "2024-11-15": {
      "key_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "requests": 12,
      "tokens_in": 49200,
      "tokens_out": 17220,
      "tokens_saved": 31980
    }
  }
}

Returns 404 if the key does not exist or does not belong to the authenticated user.

Python API

HTTP API

SuperCompress API Key Management and Usage Endpoints

Authentication

GET /api/me

Example request

Response fields

Example response

GET /api/keys

Example request

Example response

POST /api/keys

Body parameters

Example request

Example response

PATCH /api/keys/

Path parameter

Body parameters

Example request

Example response

DELETE /api/keys/

Path parameter

Example request

Example response

GET /api/keys//usage

Path parameter

Example request

Response fields

Example response

​Authentication

​GET /api/me

​Example request

​Response fields

​Example response

​GET /api/keys

​Example request

​Example response

​POST /api/keys

​Body parameters

​Example request

​Example response

​PATCH /api/keys/

​Path parameter

​Body parameters

​Example request

​Example response

​DELETE /api/keys/

​Path parameter

​Example request

​Example response

​GET /api/keys//usage

​Path parameter

​Example request

​Response fields

​Example response

Authentication

GET /api/me

Example request

Response fields

Example response

GET /api/keys

Example request

Example response

POST /api/keys

Body parameters

Example request

Example response

PATCH /api/keys/

Path parameter

Body parameters

Example request

Example response

DELETE /api/keys/

Path parameter

Example request

Example response

GET /api/keys//usage

Path parameter

Example request

Response fields

Example response