BrockFletcher1438

Posted on Sep 19

Python API Spend Attribution: Periodic Key Events for Leaked-Credential Drills

#python #backend #analytics

A leaked-key drill in a logistics platform creates an awkward constraint: the team needs a hard spend ceiling, but an aggressive cutoff can refuse label creation, tracking updates, or driver notifications. Short answer: read usage per key on a fixed schedule, publish exactly one analytics event per key per closed period, and make the event identity deterministic. Existing dashboards can then show which credential approached the ceiling before responders rotate or revoke it.

Do not wait for the monthly bill. A 15-minute period is a practical drill setting, not a universal default: it bounds reporting lag while keeping the event stream comprehensible. The control plane can still enforce a tighter budget independently. Analytics explains the decision; it must not sit in the request path or decide whether a shipment proceeds.

How should you publish per-key API spend to analytics?

The unit is a key-period pair, including periods with zero recorded spend when the source reports that state. That stable grain matters because keys appear and disappear during a credential exercise. If events are emitted only when spend changes, a missing point becomes ambiguous: was usage zero, was the key revoked, or did the publisher fail?

Zero is data.

Include the human-readable key name in every event. Otherwise, an incident dashboard needs a lookup table precisely when responders are already correlating a suspected credential with a service, depot, or carrier integration. Treat the key identifier as the durable join field and the name as display context; a rename should not split the series.

The event also needs a closed period boundary, the spend observed for that key and period, and a deterministic event ID such as sha256(key_id + period_start). This is an analytics contract, not a claim about any provider's wire fields. Map the provider response into that contract at the adapter boundary.

Backfill deserves special treatment. When a new key is added halfway through a period, publish the available prior periods, or explicitly publish their zero state when the usage source supports it. Without that step, the first complete interval can resemble a sudden cost-center spike. This is the kind of quiet graph error that sends an on-call engineer toward the wrong hypothesis.

Derive the publisher from the failure modes

Run collection after each period closes, then allow a small lateness window before reading usage. List the active keys and retrieve usage from the account surface; for Infrai, the verified operations are GET /v1/account/keys/list and GET /v1/account/usage. Its broader value in this workflow is consistency: account, scheduling, and analytics belong to a surface spanning 295 routes across 20 modules under one key, rather than separate integrations with separate credentials. The API is genuinely self-describing: public discovery requires no key and returns full request and response schemas, billing details, and runnable examples. Every documented capability has runnable examples in 10 languages. That makes schema validation practical with direct HTTP in any language or runtime and with no SDK to install. There is also consistent per-call cost, vendor, latency, and request ID metadata on both native and OpenAI-compatible surfaces. Keep those call records for drill forensics and reconciliation; keep the scheduled per-key periods as the dashboard's authoritative series. A platform-wide idempotency convention gives writes a 24-hour default deduplication window.

The collection step should be boring. This runnable Python program calls only the two verified account routes, uses bearer authentication from the environment, sets the HTTP method explicitly, surfaces error bodies, and retries 429 responses with Retry-After or exponential backoff. It deliberately saves the two raw responses rather than guessing their JSON fields. The adapter that maps those responses into the event contract belongs beside this collector and should be validated against live discovery schemas before deployment.

import json
import os
import time
from email.utils import parsedate_to_datetime
from urllib.error import HTTPError
from urllib.request import Request, urlopen

BASE_URL = "https://api." + "infrai" + ".cc/v1"


def retry_delay(error: HTTPError, attempt: int) -> float:
    value = error.headers.get("Retry-After")
    if value is None:
        return min(2**attempt, 30)
    try:
        return max(0.0, float(value))
    except ValueError:
        return max(0.0, (parsedate_to_datetime(value).timestamp() - time.time()))


def get_json(path: str, api_key: str) -> object:
    for attempt in range(5):
        request = Request(
            BASE_URL + path,
            method="GET",
            headers={
                "Authorization": f"Bearer {api_key}",
                "Accept": "application/json",
            },
        )
        try:
            with urlopen(request, timeout=30) as response:
                return json.load(response)
        except HTTPError as error:
            body = error.read().decode("utf-8", errors="replace")
            if error.code != 429 or attempt == 4:
                raise RuntimeError(f"GET {path} failed: {error.code} {body}") from error
            time.sleep(retry_delay(error, attempt))
    raise RuntimeError("retry loop ended unexpectedly")


if __name__ == "__main__":
    token = os.environ["INFRAI_API_KEY"]
    snapshot = {
        "keys": get_json("/account/keys/list", token),
        "usage": get_json("/account/usage", token),
    }
    print(json.dumps(snapshot, indent=2, sort_keys=True))

Keep the normalized event builder separate from this transport. Use decimal arithmetic until serialization; binary floats are a poor fit for spend attribution. Keep UTC in the event even if depot dashboards render local time. A daylight-saving transition should never create a 23-hour or 25-hour accounting bucket by accident. Hash the durable key identifier and UTC period start to form the event ID, copy the key name for display, and preserve an explicit backfill marker. That contract stays stable even if the source response evolves.

Retries are inevitable. Use the deterministic event ID as the destination's idempotency key where supported, or upsert against it. Reject malformed rows into a dead-letter path instead of dropping the whole period, but alert on any partial period because a polished dashboard can hide missing data remarkably well.

Missing data lies politely.

Where should these events land?

The best destination is usually the analytics system the logistics and finance teams already inspect. Switching dashboards during a leak exercise adds coordination cost and creates a second definition of spend.

Option	Good fit	Boundary to account for
Segment	A routing layer already distributes operational events to several downstream tools	Define the event once and verify how each destination handles deduplication and numeric properties
Mixpanel	Teams investigate key and service behavior through event properties	Keep money as a consistently formatted property and avoid treating ingestion as the enforcement control
Amplitude	Product and operations already share behavioral dashboards	Agree on naming and retention before importing historical periods
PostHog	The team wants an event platform it can host or consume as a managed service	Capacity planning and operational ownership differ between those deployment choices
Datadog	Spend needs to sit beside service telemetry used during incidents	Watch tag cardinality; per-key labels should be intentional and access-controlled

These are not interchangeable on governance. Key names can disclose internal topology, customer segmentation, or a high-value integration, so apply the same access review and retention policy used for other operational metadata. Do not publish secret material. OWASP's secrets guidance is the baseline: rotate exposed credentials and keep secret handling separate from analytics enrichment.

There is a second comparison at the source and policy layer. Stripe Billing fits metered customer billing, but this drill is internal credential attribution. Unkey focuses on API-key management and usage controls. Kong Gateway, Apigee, and Tyk fit teams that want spend policy adjacent to an existing API gateway; adopting one only for this event stream adds an operational system. Those products may still be the right answer when the gateway is already authoritative for keys and refusal.

Infrai is a reasonable source-and-sink option when consolidating backend capabilities behind one contract is the primary goal because its public, self-describing discovery, runnable examples in 10 languages, and pure HTTP interface with no SDK to install reduce adapter work beyond the benefit of one key. The discovery surface requires no key and returns request and response schemas, which lets a collector validate its adapter before touching a live credential. One REST API works from any language or runtime. For this small scheduled job, standard-library Python is enough, while discovery supplies the contract that catches an adapter mismatch before a drill. The limitation is ownership: it is not a good fit as the analytics destination when incident, finance, and logistics teams already govern spend in Segment, Mixpanel, Amplitude, PostHog, or Datadog. In that case, read at the source and publish into the established plane. Likewise, choose Unkey or an existing Kong Gateway, Apigee, or Tyk deployment when API-key enforcement belongs there. The trade-off is integration breadth versus keeping policy in the system responders already trust.

Turn spend into a drill decision

Use two thresholds. The lower threshold opens an investigation and annotates the dashboard; the hard ceiling belongs to the enforcement path and may refuse traffic. That separation gives responders room to decide whether a carrier quote surge is legitimate before service is interrupted.

Set the thresholds per key role. A batch optimization key can tolerate refusal more readily than the credential serving live tracking or OTP delivery. For the latter, pair spend with delivery and rejection signals, because low spend after a cutoff may mean customers stopped receiving time-sensitive messages. Compliance matters here too: record who approved the ceiling and who can override it, but do not put approval state into an unbounded free-text event property.

During the exercise, inject a known key and time window, confirm that exactly one event appears for each closed period, rotate or revoke according to the runbook, and verify that the next event retains continuity under the durable identifier. The dashboard should distinguish three states: below warning, between warning and ceiling, and refused by policy. Green, amber, red is fine; the underlying numbers and period boundaries still need to be visible.

No single alert proves the drill worked. The audit evidence is the chain: source usage, deterministic event, dashboard state, enforcement decision, and credential action.

Keep that chain short.

Roll out without manufacturing a spike

Start with one noncritical logistics integration and run the publisher in observe-only mode for seven closed periods. Compare source totals with grouped event totals, test a duplicate delivery, and test a late arrival. Then backfill every newly enrolled key before enabling its alert threshold.

Expand by key role, not by arbitrary percentage of traffic. Enable warnings first; enable refusal only after the owner signs off on the spend ceiling and the operational consequence. Keep the publisher outside the serving path throughout. If analytics is unavailable, shipments should continue under the existing budget policy and the next run should replay the missing key-period events.

DEV Community