Validation & observability

Use the validation endpoint to confirm API keys are active and to surface metadata for monitoring.

Checking keys at startup

from simulacrum import Simulacrum
from simulacrum.exceptions import AuthError

client = Simulacrum(api_key="sim-key_id-secret")
try:
    validation = client.validate()
except AuthError as exc:
    raise SystemExit(f"API key rejected: {exc}")

if not validation.valid:
    raise SystemExit("API key is inactive or expired")

Store validation results with your service telemetry. The response exposes the owning client ID and expiration timestamp when available.

Surfacing expiration alerts

from datetime import datetime, timedelta

expires_at = validation.expires_at
if expires_at and expires_at < datetime.utcnow() + timedelta(days=7):
    notify("Simulacrum API key expires soon", severity="warning")

Trigger alerts a week ahead so you can rotate keys without outages.

Programmatic health checks

validate() executes a lightweight GET request. Schedule it in your orchestrator to confirm network reachability and authentication.

import asyncio

async def readiness_probe(client: Simulacrum) -> None:
    loop = asyncio.get_event_loop()
    await loop.run_in_executor(None, client.validate)

If the call raises AuthError, rotate the key. Any other SimulacrumError indicates upstream issues: retry with backoff and alert your on-call channel.

Start here

Core workflows

Validation & observability

Validation & observability

Checking keys at startup

Surfacing expiration alerts

Programmatic health checks

​Validation & observability

​Checking keys at startup

​Surfacing expiration alerts

​Programmatic health checks

Validation & observability

Checking keys at startup

Surfacing expiration alerts

Programmatic health checks