Back to Home
This documentation covers Node.js (Express) and Python (FastAPI) integration. SDKs for Flask and Next.js are in active development.

1) Install

npm i warning_sdk

2) Create a Project

  • Create an account, then open the dashboard.
  • Create a project and copy the generated project_id.
  • Make sure your account has credits (Billing page) so ingestion isn't blocked.

3) Add the Middleware

const express = require("express");
const sdk = require("warning_sdk");

const app = express();

// If you run behind a proxy/load balancer, this improves req.ip correctness:
app.set("trust proxy", true);

app.use(
    sdk.express({
        url: "https://warning-sdk.gdani.eu/collect/v1",
        project_id: "YOUR_PROJECT_ID",
        // Optional: capture an API key for credential-sharing detection
        apiKeys: { scheme: "bearer" },
    })
);

// Rest of the server side ...

app.get("/health", (req, res) => res.json({ ok: true }));
app.listen(3000);
Note: the backend trusts project_id and resolves the project name server-side. Any client-sent project_name is ignored.

Auth / API Key Capture

If you pass apiKeys, the SDK extracts an API key and sends it as api_key. For bearer it reads Authorization: Bearer ...; otherwise it looks for name in headers (case-insensitive), then query, then body.

Bearer token
// Config
apiKeys: { scheme: "bearer" }

// Request header
Authorization: Bearer <token>
Custom header
// Config
apiKeys: { scheme: "header", name: "x-api-key" }

// Request header
X-API-KEY: <token>
Query param
// Config
apiKeys: { scheme: "query", name: "api_key" }

// Example
GET /demo?api_key=<token>
Body field
// Config
apiKeys: { scheme: "body", name: "api_key" }

// Example JSON body
{ "api_key": "<token>" }

Troubleshooting

  • No data in dashboard: verify project_id, credits, and that the backend is reachable at /collect/v1.
  • 426 Upgrade Required: you are missing X-SDK-Version (the SDK sets it automatically; custom curl calls must include it).
Want help? Share your collector URL + a redacted config snippet and I’ll sanity-check it.

1) Install

pip install warning-sdk-fastapi

2) Create a Project

  • Create an account, then open the dashboard.
  • Create a project and copy the generated project_id.
  • Make sure your account has credits (Billing page) so ingestion isn't blocked.

3) Add the Middleware

from fastapi import FastAPI

from warning_sdk_fastapi import WarningSDKApiKeysConfig, WarningSDKConfig, WarningSDKMiddleware

app = FastAPI()

app.add_middleware(
    WarningSDKMiddleware,
    config=WarningSDKConfig(
        url="https://warning-sdk.gdani.eu/collect/v1",
        project_id="YOUR_PROJECT_ID",
        # Optional: capture an API key for credential-sharing detection
        api_keys=WarningSDKApiKeysConfig(scheme="bearer"),
    ),
)

@app.get("/health")
def health():
    return {"ok": True}
Note: the backend trusts project_id and resolves the project name server-side. Any client-sent project_name is ignored.

Client IPs (Behind Proxies)

If you deploy behind a reverse proxy / load balancer, your app will otherwise see the proxy IP (and the SDK will send that). Enable proxy headers so FastAPI/Uvicorn uses X-Forwarded-For/Forwarded safely.

  • What it means: --forwarded-allow-ips is the list/CIDRs of proxies you trust to set forwarded headers.
  • How do I know what to put there? Use the IP(s)/CIDR of the proxy/load balancer that sits in front of your app (Nginx/Traefik/ALB/Cloudflare/Render/etc.). For local dev it’s usually 127.0.0.1 (or your Docker network CIDR).
uvicorn main:app --proxy-headers --forwarded-allow-ips="127.0.0.1"

Auth / API Key Capture

If you pass api_keys, the SDK extracts an API key and sends it as api_key. For bearer it reads Authorization: Bearer ...; otherwise it looks for name in headers (case-insensitive), then query, then body.

Bearer token
# Config
api_keys=WarningSDKApiKeysConfig(scheme="bearer")

# Request header
Authorization: Bearer <token>
Custom header
# Config
api_keys=WarningSDKApiKeysConfig(scheme="header", name="x-api-key")

# Request header
X-API-KEY: <token>
Query param
# Config
api_keys=WarningSDKApiKeysConfig(scheme="query", name="api_key")

# Example
GET /demo?api_key=<token>
Body field
# Config
api_keys=WarningSDKApiKeysConfig(scheme="body", name="api_key")

# Example JSON body
{ "api_key": "<token>" }

Troubleshooting

  • No data in dashboard: verify project_id, credits, and that the backend is reachable at /collect/v1.
  • 426 Upgrade Required: you are missing X-SDK-Version (the SDK sets it automatically; custom curl calls must include it).
Want help? Share your collector URL + a redacted config snippet and I’ll sanity-check it.