signed_up_at_millis JWT claim

apps/backend/src/lib/tokens.tsx

@@ -314,6 +314,7 @@ export async function generateAccessTokenFromRefreshTokenIfValid(options: Refres
     email: user.primary_email,
     email_verified: user.primary_email_verified,
     selected_team_id: user.selected_team_id,
+    signed_up_at_millis: user.signed_up_at_millis,
     is_anonymous: user.is_anonymous,
     is_restricted: user.is_restricted,
     restricted_reason: user.restricted_reason,

apps/e2e/tests/backend/backend-helpers.ts

@@ -299,6 +299,7 @@ export namespace Auth {
         "iss": expectedIssuer,
         "branch_id": "main",
         "refresh_token_id": expect.any(String),
+        "signed_up_at_millis": expect.any(Number),
         "requires_totp_mfa": expect.any(Boolean),
         "aud": backendContext.value.projectKeys === "no-project" ? expect.any(String) : backendContext.value.projectKeys.projectId,
         "sub": expect.any(String),

apps/e2e/tests/js/access-token-refresh.test.ts

@@ -366,6 +366,37 @@ describe("access token refresh on user property changes", () => {
     });
   });
 
+  describe("signed_up_at_millis claim", () => {
+    it("should include signed_up_at_millis and keep it stable across token refreshes", async ({ expect }) => {
+      const { clientApp } = await createApp({
+        config: {
+          credentialEnabled: true,
+        },
+      });
+
+      await clientApp.signUpWithCredential({
+        email: "test@example.com",
+        password: "password123",
+        verificationCallbackUrl: "http://localhost:3000",
+      });
+
+      const user = await clientApp.getUser({ or: "throw" });
+      const initialToken = await user.getAccessToken();
+      expect(initialToken).toBeDefined();
+
+      const initialPayload = decodeAccessToken(initialToken!);
+      expect(initialPayload.signed_up_at_millis).toBe(user.signedUpAt.getTime());
+
+      await user.setDisplayName("Updated display name");
+
+      const refreshedToken = await user.getAccessToken();
+      expect(refreshedToken).toBeDefined();
+
+      const refreshedPayload = decodeAccessToken(refreshedToken!);
+      expect(refreshedPayload.signed_up_at_millis).toBe(user.signedUpAt.getTime());
+    });
+  });
+
   describe("getAccessToken reflects current state", () => {
     it("should always return a token reflecting the current user state", async ({ expect }) => {
       const { clientApp, serverApp } = await createApp({

claude/CLAUDE-KNOWLEDGE.md

@@ -153,3 +153,6 @@ A: In `packages/template/src/components-page/stack-handler-client.tsx`, parse ha
 
 Q: What is the current `app.urls` contract after deprecating runtime URL mutation?
 A: `app.urls` is now static (`getUrls(...)` only) and no longer injects runtime `after_auth_return_to` / `stack_cross_domain_*` params from `window.location`. For navigation flows, examples and consumers should use `redirectToXyz()` methods instead (for example `redirectToSignIn()` / `redirectToSignOut()`), while tests for hosted flows should assert dynamic params on actual redirect methods, not on `app.urls`.
+
+Q: How should new JWT claims be rolled out without breaking old access tokens?
+A: Add the claim to token generation in `apps/backend/src/lib/tokens.tsx`, but keep the decode schema backward-compatible by adding the field as optional in `packages/stack-shared/src/schema-fields.ts` with a `// TODO next-release` to later switch it to `.defined()` after all deployments issue the new claim.

docs/content/docs/(guides)/concepts/jwt.mdx

@@ -47,6 +47,7 @@ Stack Auth JWTs contain standardized headers and claims that power authenticatio
 - **`email`**: The user's primary email address (nullable)
 - **`email_verified`**: Whether the user's email has been verified
 - **`selected_team_id`**: The currently selected team ID (nullable)
+- **`signed_up_at_millis`**: When this user signed up (Unix timestamp in milliseconds)
 - **`is_anonymous`**: Whether this is an anonymous user session
 - **`is_restricted`**: Whether the user is restricted (e.g., unverified email, anonymous, or restricted by an administrator)
 - **`restricted_reason`**: Why the user is restricted (nullable). The `type` field is `anonymous`, `email_not_verified`, or `restricted_by_administrator`
@@ -71,6 +72,7 @@ Here's what a typical Stack Auth JWT payload looks like:
   "email": "john@example.com",
   "email_verified": true,
   "selected_team_id": "team_789",
+  "signed_up_at_millis": 1735000000000,
   "is_anonymous": false,
   "is_restricted": false,
   "restricted_reason": null,

packages/stack-shared/src/schema-fields.ts

@@ -789,6 +789,8 @@ export const accessTokenPayloadSchema = yupObject({
   email: yupString().defined().nullable(),
   email_verified: yupBoolean().defined(),
   selected_team_id: yupString().defined().nullable(),
+  // TODO next-release: make this .defined() once all deployments generate signed_up_at_millis in access tokens
+  signed_up_at_millis: signedUpAtMillisSchema.optional(),
   is_anonymous: yupBoolean().defined(),
   is_restricted: yupBoolean().defined(),
   restricted_reason: restrictedReasonSchema.defined().nullable(),