Admin API

Admin API & Key Management

The admin API lets you issue time‑limited API keys, list them, and revoke them. Keys are stored in the api_keys table in your PostgreSQL database.

Authentication

Every admin endpoint requires the X-Admin-Key header to match your ADMIN_KEY environment variable. A mismatch returns:

{ "error": "Unauthorized admin access." }   // 401

All admin endpoints use POST.

---

Database schema

The api_keys table is created automatically on startup:

CREATE TABLE IF NOT EXISTS api_keys (
    key         VARCHAR(255) PRIMARY KEY,
    expires_at  TIMESTAMP WITH TIME ZONE NOT NULL,
    created_at  TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    status      VARCHAR(50) DEFAULT 'active'
);

Column	Meaning
key	The generated key string (format: saeed_ + 24 hex chars).
expires_at	UTC timestamp after which the key is rejected.
created_at	UTC creation time.
status	active or revoked.

---

POST /v1/admin/create-key

Creates a new API key with a fixed lifespan.

Headers

Header	Value
X-Admin-Key	Your ADMIN_KEY.

Body / query parameter

Parameter	Type	Allowed values	Description
duration	integer	1, 3, 7, 30	Key lifespan in days.

duration may be passed as a query string (?duration=7) or as a JSON body field.

Example

curl -X POST "http://127.0.0.1:5000/v1/admin/create-key?duration=7" \
     -H "X-Admin-Key: Your_admin_Key"

# JSON body variant
curl -X POST "http://127.0.0.1:5000/v1/admin/create-key" \
     -H "X-Admin-Key: Your_admin_Key" \
     -H "Content-Type: application/json" \
     -d '{"duration": 30}'

Success — 200 OK

{
  "status": "success",
  "key": "saeed_3f9a1c4b7e2d8a6f0b1c2d3e",
  "duration_days": 7,
  "expires_at": "2026-07-02T12:34:56.789012+00:00"
}

Errors

Status	Body	Cause
400	{"error": "Invalid duration. Must be an integer ..."}	duration missing or not an integer.
400	{"error": "Invalid duration. Supported lifespans: 1, 3, 7, 30 days."}	Value not in the allowed set.
401	{"error": "Unauthorized admin access."}	Bad X-Admin-Key.
500	{"error": "Database operation failed."}	DB insert failed.

---

POST /v1/admin/list-keys

Returns all keys, newest first.

curl -X POST "http://127.0.0.1:5000/v1/admin/list-keys" \
     -H "X-Admin-Key: Your_admin_Key"

Success — 200 OK

{
  "keys": [
    {
      "key": "saeed_3f9a1c4b7e2d8a6f0b1c2d3e",
      "expires_at": "2026-07-02T12:34:56+00:00",
      "created_at": "2026-06-25T12:34:56+00:00",
      "status": "active"
    }
  ]
}

---

POST /v1/admin/revoke-key

Marks a key as revoked (does not delete the row). Revoked keys are rejected by /v1/auth.

Parameter

Parameter	Type	Description
key	string	The key to revoke. Accepts query string ?key=... or JSON body.

curl -X POST "http://127.0.0.1:5000/v1/admin/revoke-key?key=saeed_3f9a1c4b7e2d8a6f0b1c2d3e" \
     -H "X-Admin-Key: Your_admin_Key"

Success — 200 OK

{ "status": "success", "message": "Key saeed_3f9a1c4b7e2d8a6f0b1c2d3e has been revoked." }

Errors

Status	Body	Cause
400	{"error": "Missing key to revoke."}	No key provided.
401	{"error": "Unauthorized admin access."}	Bad X-Admin-Key.
404	{"error": "Key not found."}	No row matched the key.
500	{"error": "Database operation failed."}	DB update failed.

---

Notes

• The master VALID_API_KEY is not stored in the database and cannot be revoked through this API — rotate it via the environment variable.
• Generated keys are cryptographically random (secrets.token_hex), so they are safe to hand out individually.