Mint one access token and reuse it

curl "https://api.brellium.com/v2/oauth/token" \
  --request POST \
  --header "Content-Type: application/json" \
  --data "{
    \"grant_type\": \"client_credentials\",
    \"client_id\": \"$BRELLIUM_CLIENT_ID\",
    \"client_secret\": \"$BRELLIUM_CLIENT_SECRET\",
    \"audience\": \"${BRELLIUM_AUDIENCE:-https://api.brellium.dev}\"
  }"

const res = await fetch("https://api.brellium.com/v2/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: process.env.BRELLIUM_CLIENT_ID,
    client_secret: process.env.BRELLIUM_CLIENT_SECRET,
    audience: process.env.BRELLIUM_AUDIENCE || "https://api.brellium.dev",
  }),
});
if (!res.ok)
  throw new Error(`token request failed: ${res.status} ${await res.text()}`);
console.log(await res.json());

// Keep credentials on the server; never in a browser or mobile app.
const BASE_URL = "https://api.brellium.com";
const AUDIENCE = process.env.BRELLIUM_AUDIENCE ?? "https://api.brellium.dev";
// Refresh five minutes early, so a request never carries a token that expires
// mid-call.
const EARLY_REFRESH_MS = 300_000;

type TokenResponse = {
  access_token: string;
  token_type: string;
  expires_in: number;
  scope?: string;
};
type CachedToken = { token: string; expiresAt: number };

const sleep = (ms: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, ms));

/**
 * Milliseconds to wait after a 429: Retry-After, else RateLimit-Reset, else one
 * second.
 */
function retryAfterMs(res: Response): number {
  const header =
    res.headers.get("Retry-After") ?? res.headers.get("RateLimit-Reset");
  const seconds = Number(header);
  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 1_000;
}

/**
 * One instance per client_id. Share it across the process; never share a token
 * between keys.
 */
export class TokenManager {
  private readonly clientId: string;
  private readonly clientSecret: string;
  private cached: CachedToken | undefined;
  private inFlight: Promise<string> | undefined;

  constructor(clientId: string, clientSecret: string) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
  }

  /** The cached token, or one mint that every concurrent caller waits for. */
  async get(): Promise<string> {
    if (this.cached && Date.now() < this.cached.expiresAt) return this.cached.token;
    if (!this.inFlight) {
      this.inFlight = this.mint().finally(() => {
        this.inFlight = undefined;
      });
    }
    return this.inFlight;
  }

  /**
   * Drop a token the API rejected, so the next get() mints. A newer token is left
   * alone.
   */
  invalidate(token: string): void {
    if (this.cached?.token === token) this.cached = undefined;
  }

  private async mint(): Promise<string> {
    for (let attempt = 0; ; attempt++) {
      const res = await fetch(`${BASE_URL}/v2/oauth/token`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          grant_type: "client_credentials",
          client_id: this.clientId,
          client_secret: this.clientSecret,
          audience: AUDIENCE,
        }),
      });
      if (res.status === 429 && attempt < 2) {
        // The token endpoint's own limit: wait exactly what the header says.
        await sleep(retryAfterMs(res));
        continue;
      }
      if (!res.ok) {
        // Log the status and request id only, never the body of a token request or
        // response.
        throw new Error(
          `token request failed: ${res.status} (x-request-id ` +
            `${res.headers.get("x-request-id")})`,
        );
      }
      const body = (await res.json()) as TokenResponse;
      this.cached = {
        token: body.access_token,
        expiresAt: Date.now() + body.expires_in * 1000 - EARLY_REFRESH_MS,
      };
      return body.access_token;
    }
  }
}

const managers = new Map<string, TokenManager>();

/**
 * One cache per client_id: a token minted for one key is never sent on behalf of
 * another.
 */
export function tokenManagerFor(
  clientId: string,
  clientSecret: string,
): TokenManager {
  let manager = managers.get(clientId);
  if (!manager) {
    manager = new TokenManager(clientId, clientSecret);
    managers.set(clientId, manager);
  }
  return manager;
}

/**
 * Send an authenticated request. On 401, drop the token, mint once and retry once.
 */
export async function brelliumFetch(
  tokens: TokenManager,
  path: string,
  init: RequestInit = {},
): Promise<Response> {
  const send = async (token: string) => {
    const headers = new Headers(init.headers);
    headers.set("Authorization", `Bearer ${token}`);
    return fetch(`${BASE_URL}${path}`, { ...init, headers });
  };
  let token = await tokens.get();
  let res = await send(token);
  if (res.status === 401) {
    tokens.invalidate(token);
    token = await tokens.get();
    res = await send(token);
  }
  return res;
}

async function main() {
  const clientId = process.env.BRELLIUM_CLIENT_ID;
  const clientSecret = process.env.BRELLIUM_CLIENT_SECRET;
  if (!clientId || !clientSecret)
    throw new Error("Set BRELLIUM_CLIENT_ID and BRELLIUM_CLIENT_SECRET");
  const tokens = tokenManagerFor(clientId, clientSecret);

  // Two API calls, one token request: the second call reuses the cached token.
  for (let i = 0; i < 2; i++) {
    const res = await brelliumFetch(tokens, "/v2/question_sets?limit=1");
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    const page = (await res.json()) as { data: { set_name: string }[] };
    console.log(res.status, page.data[0]?.set_name ?? "(no question sets yet)");
  }
}

main();

# Keep credentials on the server; never in a browser or mobile app.
import os
import threading
import time

import requests

BASE_URL = "https://api.brellium.com"
AUDIENCE = os.environ.get("BRELLIUM_AUDIENCE", "https://api.brellium.dev")
# Refresh five minutes early, so a request never carries a token that expires
# mid-call.
EARLY_REFRESH_SECONDS = 300


def _retry_after_seconds(res: requests.Response) -> float:
    """Seconds to wait after a 429: Retry-After, else RateLimit-Reset, else one
    second.
    """
    header = (
        res.headers.get("Retry-After") or res.headers.get("RateLimit-Reset") or ""
    )
    try:
        return max(float(header), 1.0)
    except ValueError:
        return 1.0


class TokenManager:
    """One instance per client_id. Share it across threads; never share a token
    between keys.
    """

    def __init__(self, client_id: str, client_secret: str) -> None:
        self._client_id = client_id
        self._client_secret = client_secret
        self._token: str | None = None
        self._expires_at = 0.0
        # One mint at a time; concurrent callers wait for it.
        self._lock = threading.Lock()

    def get(self) -> str:
        """The cached token, or one mint that every concurrent caller waits for."""
        with self._lock:
            if self._token and time.monotonic() < self._expires_at:
                return self._token
            return self._mint()

    def invalidate(self, token: str) -> None:
        """Drop a token the API rejected, so the next get() mints. A newer token is
        left alone.
        """
        with self._lock:
            if self._token == token:
                self._token = None

    def _mint(self) -> str:
        attempt = 0
        while True:
            res = requests.post(
                f"{BASE_URL}/v2/oauth/token",
                headers={"Content-Type": "application/json"},
                json={
                    "grant_type": "client_credentials",
                    "client_id": self._client_id,
                    "client_secret": self._client_secret,
                    "audience": AUDIENCE,
                },
                timeout=30,
            )
            if res.status_code == 429 and attempt < 2:
                # The token endpoint's own limit: wait exactly what the header says.
                time.sleep(_retry_after_seconds(res))
                attempt += 1
                continue
            if not res.ok:
                # Log the status and request id only, never the body of a token
                # request or response.
                raise RuntimeError(
                    f"token request failed: {res.status_code} "
                    f"(x-request-id {res.headers.get('x-request-id')})"
                )
            body = res.json()
            self._token = body["access_token"]
            self._expires_at = (
                time.monotonic() + body["expires_in"] - EARLY_REFRESH_SECONDS
            )
            return self._token


_managers: dict[str, TokenManager] = {}
_managers_lock = threading.Lock()


def token_manager_for(client_id: str, client_secret: str) -> TokenManager:
    """One cache per client_id: a token minted for one key is never sent on behalf
    of another.
    """
    with _managers_lock:
        if client_id not in _managers:
            _managers[client_id] = TokenManager(client_id, client_secret)
        return _managers[client_id]


def brellium_request(
    tokens: TokenManager, method: str, path: str, **kwargs
) -> requests.Response:
    """Send an authenticated request. On 401, drop the token, mint once and retry
    once.
    """
    kwargs.setdefault("timeout", 30)

    def send(token: str) -> requests.Response:
        headers = {**kwargs.get("headers", {}), "Authorization": f"Bearer {token}"}
        return requests.request(
            method, f"{BASE_URL}{path}", **{**kwargs, "headers": headers}
        )

    token = tokens.get()
    res = send(token)
    if res.status_code == 401:
        tokens.invalidate(token)
        token = tokens.get()
        res = send(token)
    return res


if __name__ == "__main__":
    tokens = token_manager_for(
        os.environ["BRELLIUM_CLIENT_ID"], os.environ["BRELLIUM_CLIENT_SECRET"]
    )

    # Two API calls, one token request: the second call reuses the cached token.
    for _ in range(2):
        res = brellium_request(tokens, "GET", "/v2/question_sets?limit=1")
        if not res.ok:
            raise RuntimeError(f"{res.status_code} {res.text}")
        page = res.json()
        print(
            res.status_code,
            page["data"][0]["set_name"]
            if page["data"]
            else "(no question sets yet)",
        )

curl "https://api.brellium.com/v2/question_sets?limit=1" \
  --header "Authorization: Bearer $BRELLIUM_ACCESS_TOKEN" \
  --write-out "HTTP %{http_code}\n"

const res = await fetch("https://api.brellium.com/v2/question_sets?limit=1", {
  headers: { Authorization: `Bearer ${process.env.BRELLIUM_ACCESS_TOKEN}` },
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message}`);
}
console.log(await res.json(), `HTTP ${res.status}`);

import BrelliumClient, { APIError } from "@brellium/api-client";

const client = new BrelliumClient({ oAuth2: process.env.BRELLIUM_ACCESS_TOKEN });

try {
  const questionSets = await client.questionSets.list({ limit: 1 });
  console.log(questionSets);
} catch (err) {
  if (err instanceof APIError && err.status === 401) {
    console.error(
      "401: invalidate the token, mint a new one, retry once",
      err.error,
    );
  } else {
    throw err;
  }
}

import os
import sys

from brellium_api_client import AuthenticationError, BrelliumClient

client = BrelliumClient(o_auth2=os.environ["BRELLIUM_ACCESS_TOKEN"])

try:
    question_sets = client.question_sets.list(limit=1)
    print(question_sets.to_json())
except AuthenticationError as err:  # 401
    print(
        "401: invalidate the token, mint a new one, retry once",
        err.body,
        file=sys.stderr,
    )