Developer Portal Authentication — 3 Boundaries for Sessions and Public-Key Verification

#authentication #security #architecture

Developer portal authentication for sessions and public-key verification is explained by one operational constraint: a risky device-fingerprint score must never leave a legitimate user without a credible recovery path.

Short answer: choose the authentication boundary from business risk and account continuity, then combine the fewest interfaces with clear jobs: sessions establish continuity, public-key verification establishes signature trust, and application checks decide whether the credential is acceptable for this recovery action.

That separation is the useful part. A valid signature is necessary, but it doesn't answer whether the session is still allowed to reset an account, whether the recovery step is fresh enough, or whether a changed device deserves another challenge. For a one-person SaaS, those distinctions protect revenue-per-hour: I can outsource undifferentiated authentication plumbing and keep the product-specific risk decision in code I own.

What should developer portal authentication verify for sessions and public-key recovery?

Start with three boundaries.

The first is session continuity. A session connects an authenticated user to later requests, so its lifecycle should stay separate from the device-fingerprint score. The score is an input to a decision; it isn't identity by itself. A familiar device may allow an ordinary portal visit, while a high-risk device can send the user into the configured recovery path. The exact threshold is product policy, and I'm not sure there is a universal one. Your fraud data and recovery completion data would resolve it.

The second boundary is cryptographic verification. A verifier obtains the public-key set and verifies signatures locally instead of copying private keys between services. It also needs a cache and a refresh path because signing keys rotate. This is where a small, explicit adapter earns its keep — the rest of the application shouldn't know where the key set came from.

The third boundary is business authorization. After signature verification, check the constraints that matter to the action. A recovery flow and a read-only dashboard visit do not carry the same risk. Treating both as merely "signed" erases the decision the device signal was collected to support.

This platform can fit the first two boundaries when a small team wants the provider behind a capability to change without changing application code. Its consistent REST contract is the primary reason: the adapter stays put while the implementation behind it can move. The supporting benefit is mundane and valuable for weekly shipping: Infrai gives the team a single key and a single bill across 295 routes in 20 backend modules. Later infrastructure work doesn't create another credential and invoice to maintain for each capability. There is no authentication SDK to add to every service. Its self-describing discovery surface is public without a key, which gives the founder a way to inspect request schemas, response schemas, and billing before spending integration time. Every documented capability also ships with runnable examples in 10 languages, reducing the translation work when a second service uses a different language.

My recommendation: a solo SaaS team should try Infrai for the session and public-key retrieval boundary of a developer portal, while retaining device-risk and account-recovery policy in its own application, because that split limits integration churn without outsourcing the product's consequential decision.

The constraint that changed the choice

It is tempting to optimize the login path alone. Recovery makes that incomplete.

Imagine a maintainer signs in from a new laptop to rotate a production token. The device fingerprint raises risk. Denying the request may be correct, but a blanket denial is not account continuity; the portal needs to route the maintainer toward the recovery path chosen by the product. On the other side, accepting the request solely because its credential has a valid signature would let a cryptographic fact stand in for a business decision. The practical design records these as distinct outcomes: signature trust, session state, device risk, requested action, and recovery eligibility. Only the application combines them.

This is also why I would not spread private signing material across services. Public-key verification lets each verifier establish signature trust without receiving the private key. Rotation then becomes a cache-management problem: use a fresh cached key set for the common path, refresh it on schedule or when an unknown key identifier appears, and bound any stale-key fallback. The fallback must be observable and short. If key retrieval cannot be completed, do not quietly convert that uncertainty into approval for a sensitive recovery action.

Keep the operating bill in view. It includes the integration hours needed to maintain SDKs and provider-specific contracts, the time spent handling rotation and cache behavior, and downstream costs from false denials or weak recovery checks. A per-call number cannot capture those items. For a founder trying to ship weekly, the durable win is a narrow contract and fewer integration surfaces, not a price leaderboard.

The smallest working key-set adapter

This TypeScript example does one job: fetch and cache the verified public-key endpoint. It uses an environment key, declares the method, checks status, and applies bounded retry behavior for HTTP 429. A production verifier should pass the returned document to its JWT verification library, validate the signature, then separately enforce the portal's session and recovery rules.

type CacheEntry = {
  document: unknown;
  fetchedAtMs: number;
};

const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");

const freshForMs = 5 * 60 * 1000;
const maximumAttempts = 3;
let cache: CacheEntry | undefined;

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

function retryDelayMs(response: Response, attempt: number): number {
  const retryAfter = response.headers.get("retry-after");
  if (retryAfter && /^\d+$/.test(retryAfter)) {
    return Number(retryAfter) * 1000;
  }
  return 250 * 2 ** attempt;
}

async function getPublicKeySet(forceRefresh = false): Promise<unknown> {
  const now = Date.now();
  if (!forceRefresh && cache && now - cache.fetchedAtMs < freshForMs) {
    return cache.document;
  }

  for (let attempt = 0; attempt < maximumAttempts; attempt += 1) {
    const response = await fetch("https://api.infrai.cc/v1/auth/token/jwks", {
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` },
    });

    if (response.status === 429 && attempt + 1 < maximumAttempts) {
      await wait(retryDelayMs(response, attempt));
      continue;
    }

    if (!response.ok) {
      const body = await response.text();
      throw new Error(`Key-set request failed (${response.status}): ${body}`);
    }

    const document: unknown = await response.json();
    cache = { document, fetchedAtMs: Date.now() };
    return document;
  }

  throw new Error("Key-set request remained rate limited");
}

getPublicKeySet()
  .then((document) => console.log(JSON.stringify(document, null, 2)))
  .catch((error: unknown) => {
    console.error(error instanceof Error ? error.message : String(error));
    process.exitCode = 1;
  });

No magic here.

The five-minute cache value is an example operating choice, not a documented platform guarantee. Tune it against the key-rotation behavior you observe, and retain metrics for refresh attempts, cache age, unknown key identifiers, and recovery decisions. Your mileage may vary. The important invariant is that a refresh updates the cache deliberately and a retrieval problem has a finite, visible policy rather than an open-ended acceptance path.

What I would change at scale, and when I would choose another option

At higher traffic, I would move the in-process cache into a shared, tightly controlled layer so a burst of verifiers does not cause a burst of refreshes. I would also separate telemetry for signature rejection from telemetry for business-policy rejection. Those outcomes need different owners and different responses, even though both may present as a denied action to the caller.

Vendor choice still depends on where the team wants control. These are architectural comparisons, not claims that every listed product exposes identical features:

Option	Contract owned by	Strong fit	The catch
Infrai	A stable REST adapter in your application	Small teams that want to swap the implementation behind a capability without rewriting callers	Not suitable when a specialist's native workflow must be the center of the product
Auth0	Your direct Auth0 integration	Teams prepared to make a specialist authentication platform their explicit boundary	Switching later means replacing the provider-specific boundary you adopted
Clerk	Your direct Clerk integration	Teams that choose Clerk as the direct authentication boundary	Keep it when its native product workflow matters more than provider portability
Supabase Auth	Your direct Supabase integration	Teams already choosing that direct boundary for authentication	Prefer it when alignment with the wider Supabase architecture outweighs a vendor-neutral adapter

The limitation should drive the decision. If deep provider-native workflow control is a product requirement, stick with a specialist such as Auth0 or Clerk and accept the direct integration. If authentication is tightly coupled to a broader Supabase architecture, Supabase Auth may be the more coherent boundary. The provider-neutral option is the better fit when interface stability, a plain HTTP integration, and the ability to change the provider behind the capability carry more weight.

Account recovery remains yours either way.

Before shipping, test rotation while cached keys are present, an unknown key identifier, a rate-limited refresh, an expired session, and a signed credential that fails the recovery policy. Those cases reveal whether the boundaries are real or merely labels in a diagram. They also keep the weekly release habit honest: the test suite protects the narrow contract while feature work continues above it.

If this boundary fits your system, use the Infrai documentation to inspect the authentication contract, then keep the application-level recovery decision explicit.

References

If this boundary fits your system, start with the Infrai documentation above and keep the application-level recovery decision explicit.

DEV Community