Trusted server-side session mint

​

Enabling the endpoint

# 32+ bytes of CSPRNG. macOS / Linux:
openssl rand -hex 32
# → 2f1e... (use that)

# Pylon Cloud:
pylon secrets set PYLON_TRUSTED_SECRET=2f1e...

# Self-hosted: set the env var on your Pylon server.

​

Wire format

POST /api/auth/sessions/trusted-mint
Content-Type: application/json
X-Pylon-Trusted-Timestamp: 1716177600
X-Pylon-Trusted-Signature: 9f8a2c... (hex HMAC-SHA256)

{
  "email": "[email protected]",
  "createIfMissing": true,
  "displayName": "Jane Doe",
  "intent": "stripe_checkout_success"
}

signed_value = "<timestamp>.<raw_request_body>"
signature    = hex(HMAC_SHA256(PYLON_TRUSTED_SECRET, signed_value))

​

Response

{
  "userId":    "usr_01H...",
  "created":   true,
  "token":     "pylon_...",
  "expiresAt": 1716264000
}

​

Failure modes

​

Example: Next.js Stripe Checkout success handler

import { NextRequest } from "next/server";
import { redirect } from "next/navigation";
import { createHmac } from "crypto";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const PYLON_URL = process.env.PYLON_TARGET!;
const TRUSTED_SECRET = process.env.PYLON_TRUSTED_SECRET!;

function sign(secret: string, ts: number, body: string) {
  return createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
}

export async function GET(req: NextRequest) {
  const sessionId = req.nextUrl.searchParams.get("session_id");
  if (!sessionId) return new Response("missing session", { status: 400 });

  const session = await stripe.checkout.sessions.retrieve(sessionId);
  if (session.payment_status !== "paid") return new Response("unpaid", { status: 402 });
  const email = session.customer_details?.email;
  if (!email) return new Response("no email", { status: 400 });

  const ts = Math.floor(Date.now() / 1000);
  const body = JSON.stringify({
    email,
    createIfMissing: true,
    displayName: session.customer_details?.name ?? undefined,
    intent: "stripe_checkout_success",
  });
  const signature = sign(TRUSTED_SECRET, ts, body);

  const mint = await fetch(`${PYLON_URL}/api/auth/sessions/trusted-mint`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Pylon-Trusted-Timestamp": String(ts),
      "X-Pylon-Trusted-Signature": signature,
    },
    body,
  });
  if (!mint.ok) {
    return new Response(`trusted-mint failed: ${await mint.text()}`, { status: 500 });
  }

  // Pass Pylon's Set-Cookie through to the browser, then redirect.
  const res = new Response(null, { status: 302, headers: { Location: "/dashboard" } });
  const setCookie = mint.headers.get("set-cookie");
  if (setCookie) res.headers.set("set-cookie", setCookie);
  return res;
}

​

Edge cases

• Multi-tenant orgs. The minted session matches what /api/auth/magic/verify produces. No tenant is auto-selected. Apps that need a tenant should call /api/auth/select-org after the user lands (the dashboard typically does this automatically, based on a stored “last org” hint).
• Locked or banned users. If the User row has a non-null disabledAt, bannedAt, lockedAt, or _deletedAt column, the endpoint returns 403 ACCOUNT_LOCKED and logs a sign_in_failed audit event. These are conventions, not framework-enforced columns. Apps that do not model lockouts can ignore them.
• Email already in use under a guest cookie. Trusted-mint does not merge guest data automatically. That behavior is specific to magic-link verify, where the user explicitly proves control of the email. If you need anonymous-cart merging on Stripe success, do it explicitly in your handler after the mint succeeds.
• Cookie pass-through to the browser. The endpoint always sends Set-Cookie, even when called server-to-server. If you do not forward the header to a browser, ignore it. The token in the response body is the same session, and it works as Authorization: Bearer pylon_….
• Rate limiting. The standard PYLON_RATE_LIMIT_MAX per-IP anonymous bucket applies. A bot that finds the endpoint URL but does not have the secret hits the rate limit within seconds and cannot get further. The secret is the real security boundary.

​

Audit log

​

Replay window

• A TLS man-in-the-middle in the request path (a corporate proxy, or a CDN that logs full bodies) can extract a usable session token within the 5-minute window.
• An attacker who steals one signed request from server logs that capture the URL and headers can replay it, once per minute, for up to 5 minutes. This is rare, since signatures live in headers and bodies are not usually logged.

• Do not log signed requests together with their headers.
• Use HTTPS end-to-end. The HMAC signature does not replace TLS.
• If your threat model needs single-use requests, add a nonce to the request body and enforce uniqueness in your own backend before calling trusted-mint. The trusted-mint endpoint does not de-duplicate requests on its own; Pylon’s audit log shows every replay.

​

Security checklist

• PYLON_TRUSTED_SECRET is 32+ bytes of CSPRNG output (openssl rand -hex 32).
• Set the secret only on machines that need to sign or verify requests. A sign-only frontend does not need to know it.
• Restrict the endpoint to your trusted server-side environments where possible. Most production Pylon deployments are public, so the secret is the only barrier against attackers.
• Keep server clocks within a few seconds of NTP. The ±5 minute window is not as wide as it looks: a 7-minute clock skew makes the endpoint stop working.
• To rotate the secret: set a new PYLON_TRUSTED_SECRET, redeploy the signing service, wait about 10 minutes for in-flight signed requests to flush, then update the Pylon side. Pylon accepts only one active secret today; multi-key rotation is planned.
• Send the audit log somewhere queryable (Tinybird, Loki, Datadog), so you can alert on a sign_in_failed spike for the trusted_mint method. Every post-signature rejection (invalid JSON, missing or invalid email, USER_NOT_FOUND, INVALID_USER_ROW, USER_INSERT_FAILED, ACCOUNT_LOCKED) emits one, with the matching meta.reason.
• Confirm the TLS terminator (Cloudflare, the Fly proxy, or similar) does not log signed-request payloads. Bodies are sensitive, even though headers usually are not.

​

HMAC requests vs. service tokens

• Service tokens leak. Once leaked, the attacker can sign in as anyone, indefinitely. This is the same blast radius as PYLON_TRUSTED_SECRET, except the secret never travels with the request, so observability tools that log headers do not capture it by accident.
• Service tokens do not bind to the request body. An attacker who captures one signed request can replay it. The HMAC signature plus timestamp stops that.
• Token rotation needs a coordinated cutover on both sides. Secret rotation is a single environment-variable change on each side; you do not deploy a new long-lived credential.