fastapi-keygate

API-key authentication, per-key rate limiting and per-key usage tracking for FastAPI — in a few lines, with zero setup (SQLite by default).

pip install fastapi-keygate

from fastapi import Depends, FastAPI
from keygate import ApiKey, KeyGate

app = FastAPI()
gate = KeyGate(app, admin_secret="change-me")  # SQLite, zero setup

@app.get("/hello")
def hello(key: ApiKey = Depends(gate.require)):
    return {"hello": key.owner_id}

if not gate.list_keys():  # demo only: mint a first key
    print("Your API key:", gate.create_key("demo-tenant", per_minute=5).key)

uvicorn app:app
curl -H "X-API-Key: kg_..." localhost:8000/hello   # 200, then 429 after 5/minute

(The package is fastapi-keygate on PyPI; you import keygate.)

Try it in 2 minutes

pip install fastapi-keygate uvicorn
curl -O https://raw.githubusercontent.com/codeSudee/fastapi-keygate/main/examples/app.py
uvicorn app:app

The terminal prints Your API key: kg_.... In a second terminal (paste your key):

curl -i localhost:8000/hello                              # 401: no key
curl -i -H "X-API-Key: kg_..." localhost:8000/hello       # 200, run it 6 times -> 429
keygate usage 1                                           # see what was counted
keygate create alice --per-minute 100                     # hand out another key

What you get

• Auth — Depends(gate.require) returns the caller's ApiKey (id, owner_id, limits). Missing/invalid/revoked → 401. Keys are read from X-API-Key or Authorization: Bearer, never from query strings (those leak into logs).
• Per-key rate limits — requests per minute and/or hour, stored on each key. Over limit → 429 with Retry-After; successful responses carry X-RateLimit-* headers.
• Usage tracking — every authenticated request is logged (timestamp, method, route, status).
• Key management — from Python or an opt-in admin API.

Keys look like kg_<prefix>_<secret>. Only a SHA-256 hash is stored; the plaintext is shown once at creation.

Managing keys

k = gate.create_key("acme", name="prod", per_minute=60, per_hour=1000)
k.key                      # plaintext, only available here
gate.list_keys("acme")     # [ApiKey, ...]
gate.revoke(k.id)
gate.usage(k.id, last_hours=24)
# UsageStats(total=…, by_status={200: …, 429: …}, by_endpoint={"GET /hello": …}, …)

Give keys scopes and guard routes with them (missing scope → 403; the "*" scope matches everything):

k = gate.create_key("acme", scopes=["read", "write"])

@app.delete("/items/{id}")
def delete(id: int, key: ApiKey = Depends(gate.require_scopes("write"))): ...

Rotate a key without downtime: new = gate.rotate(k.id, grace=timedelta(hours=24)) returns a replacement with the same owner, limits and scopes, and the old key keeps working until the grace period ends (POST /keygate/keys/{id}/rotate?grace_hours=24 in the admin API). Rate-limit counters are per key, so during the grace period the two keys each get their own allowance.

Keys never expire unless you set expires_at= (naive UTC datetime) or expires_in=timedelta(days=30); expired keys get 401. Omitted limits use KeyGate(default_per_minute=60, default_per_hour=None); pass None for unlimited.

With admin_secret set, these endpoints are mounted (header X-Admin-Secret). Without it, nothing is exposed.

Async apps

Using an async SQLAlchemy driver? AsyncKeyGate has the same features, with await:

pip install "fastapi-keygate[async]"        # + aiosqlite; use [asyncpg] for Postgres

from keygate import ApiKey, AsyncKeyGate

gate = AsyncKeyGate(app, db_url="sqlite+aiosqlite:///keygate.db", admin_secret="change-me")

@app.get("/hello")
async def hello(key: ApiKey = Depends(gate.require)):
    return {"hello": key.owner_id}

k = await gate.create_key("acme", per_minute=60)   # every management method is a coroutine

Tables are created on first use (or await gate.init()). For a shared rate-limit store use limits_uri="async+redis://host:6379" (uses the redis extra). Usage rows are written immediately (no batching in the async gate).

Command line

No code needed to manage keys (--db or KEYGATE_DB points at your database, default sqlite:///keygate.db):

keygate create acme --per-minute 60 --scope read --expires-days 30   # prints the key once
keygate list [--owner acme] [--all]
keygate rotate 1 --grace-hours 24
keygate revoke 1
keygate usage 1 --last-hours 24
keygate prune --older-than-days 90

Configuration

KeyGate(
    app,
    db_url="postgresql+psycopg://user:pw@host/db",  # any SQLAlchemy URL
    limits_uri="redis://localhost:6379",             # shared rate-limit store
    admin_secret=...,
)

Things to know

• Multiple workers: the default rate-limit store is in memory, per process. With N Uvicorn/Gunicorn workers a 60/min limit becomes up to 60×N. Use limits_uri="redis://..." (pip install fastapi-keygate[redis]) in that case.
• Why not slowapi? Rate limiting uses limits, the engine slowapi wraps. slowapi is built around per-endpoint decorators that need a request argument; keygate's limits belong to the key, so they're enforced inside the auth dependency. You can still use slowapi alongside it.
• Usage table growth: every authenticated request adds a row. Call gate.prune_usage(timedelta(days=90)) periodically (or DELETE /keygate/usage?older_than_days=90) to delete old rows.
• Busy apps: KeyGate(app, usage_batch_size=100) buffers usage rows in memory and writes them in one commit. They are flushed when the buffer fills, on gate.flush_usage(), before gate.usage() / gate.prune_usage(), and at exit. Rows still buffered are lost if the process crashes.
• Schema: tables are created on startup (create_all); there are no migrations yet.
• Not included (yet): Alembic migrations.
• Timestamps are naive UTC.

Development

pip install -e ".[dev]" && pytest

MIT licensed.

Web dashboard

A built-in UI for viewing keys, usage graphs, live rate-limit status, and editing, rotating or revoking keys.

from keygate.dashboard import mount_dashboard

gate = KeyGate(app, admin_secret="change-me")
mount_dashboard(app, gate)  # open /keygate/dashboard and sign in with the admin secret

The API lives under /keygate/dashboard/api and reads straight from the gate's own key and usage tables. Try it with sample traffic: python examples/dashboard_demo.py (secret: demo-secret), or click around the live demo (sample data, nothing saved).

The UI source is in dashboard/ (React, TypeScript, Tailwind, Framer Motion). Build it into the package with cd dashboard && npm install && npm run build, or run npm run dev for hot reload against a local API on :8000.

Plans (optional)

Cap what each owner can do. Plans are off by default:

from keygate import DEFAULT_PLANS, KeyGate

gate = KeyGate(app, admin_secret="change-me", plans=DEFAULT_PLANS)  # free / pro / team
gate.set_plan("acme", "pro")

Each owner_id gets a plan that limits active keys, per-key rate limits and scopes. Going over returns 402 with a plan_limit payload. Billing is not included: assign plans from your own code (for example from a payment webhook) with set_plan(owner_id, plan, billing_status=...).