Skip to main content

SDK Integration Examples

This page provides production-ready integration patterns for AuroraSOC APIs.

When to Use This Page​

Use this page when building service integrations, automation workers, or internal SDK wrappers.

Design Goals for Client Integrations​

  1. Centralize token acquisition and refresh
  2. Normalize retries for transient errors (429, 503, selected 500)
  3. Enforce request/response validation at boundaries
  4. Emit telemetry for latency, failures, and retry counts

Python Reference Client (httpx)​

from __future__ import annotations

import asyncio
from dataclasses import dataclass

import httpx


@dataclass
class AuroraClient:
    base_url: str
    username: str
    password: str
    timeout_s: float = 20.0

    def __post_init__(self) -> None:
        self._token: str | None = None
        self._client = httpx.AsyncClient(timeout=self.timeout_s)

    async def close(self) -> None:
        await self._client.aclose()

    async def authenticate(self) -> None:
        # Acquire JWT once and store in memory for subsequent requests.
        res = await self._client.post(
            f"{self.base_url}/auth/token",
            json={"username": self.username, "password": self.password},
        )
        res.raise_for_status()
        self._token = res.json()["access_token"]

    async def _request(self, method: str, path: str, **kwargs) -> dict:
        if not self._token:
            await self.authenticate()

        headers = kwargs.pop("headers", {})
        headers["Authorization"] = f"Bearer {self._token}"

        for attempt in range(4):
            res = await self._client.request(
                method,
                f"{self.base_url}{path}",
                headers=headers,
                **kwargs,
            )

            if res.status_code == 401 and attempt == 0:
                await self.authenticate()
                headers["Authorization"] = f"Bearer {self._token}"
                continue

            if res.status_code in (429, 503) and attempt < 3:
                await asyncio.sleep(2 ** attempt)
                continue

            res.raise_for_status()
            return res.json()

        raise RuntimeError("request retry budget exhausted")

    async def list_alerts(self, limit: int = 50) -> dict:
        return await self._request("GET", "/alerts", params={"limit": limit})

TypeScript Reference Client (fetch)​

export class AuroraClient {
  private token: string | null = null;

  constructor(
    private readonly baseUrl: string,
    private readonly username: string,
    private readonly password: string,
  ) {}

  private async authenticate(): Promise<void> {
    // Request JWT and cache it in memory.
    const res = await fetch(`${this.baseUrl}/auth/token`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ username: this.username, password: this.password }),
    });
    if (!res.ok) throw new Error(`auth failed: ${res.status}`);
    const payload = await res.json();
    this.token = payload.access_token;
  }

  private async request(path: string, init: RequestInit = {}): Promise<any> {
    if (!this.token) await this.authenticate();

    for (let attempt = 0; attempt < 4; attempt += 1) {
      const res = await fetch(`${this.baseUrl}${path}`, {
        ...init,
        headers: {
          ...(init.headers ?? {}),
          Authorization: `Bearer ${this.token}`,
        },
      });

      if (res.status === 401 && attempt === 0) {
        await this.authenticate();
        continue;
      }

      if ((res.status === 429 || res.status === 503) && attempt < 3) {
        await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 1000));
        continue;
      }

      if (!res.ok) throw new Error(`request failed: ${res.status}`);
      return res.json();
    }

    throw new Error("retry budget exhausted");
  }

  async listAlerts(limit = 50): Promise<any> {
    return this.request(`/alerts?limit=${limit}`);
  }
}

Edge Cases to Cover in Tests​

CaseWhy It MattersExpected Behavior
Token expires mid-sessionCommon in long-lived clientsRefresh token once, replay request
429 bursts under loadProtects service stabilityBackoff with jitter, bounded retries
503 dependency degradationPrevents false failure stormsRetry with cap, surface partial outage
Duplicate alert submissionsPrevent duplicate incidentsHandle dedup/conflict semantics cleanly

Performance Guidance​

  • Reuse HTTP clients/connections.
  • Batch low-priority polling calls where possible.
  • Keep request timeouts explicit per operation type.
  • Track p95 latency and retry rate in telemetry dashboards.