feat(user-management): add max_age parameter to getAuthorizationUrl

[imkesin]

Description

Adds support for the OIDC max_age parameter to userManagement.getAuthorizationUrl and userManagement.getAuthorizationUrlWithPKCE.

max_age specifies the maximum allowable elapsed time (in seconds) since the user last actively authenticated. If the user's last authentication is older than this value, they will be prompted to re-authenticate.

Documentation

Yes, this requires documentation changes.

[devin-ai-integration]

Devin Review found 1 potential issue.

[devin-ai-integration]

🚩 claimNonce is not forwarded in getAuthorizationUrlWithPKCE

The getAuthorizationUrlWithPKCE method does not destructure or forward claimNonce to the query string (user-management.ts:1514-1527), unlike getAuthorizationUrl which includes claim_nonce: claimNonce at line 1460. This is a pre-existing omission not introduced by this PR, but since this PR is adding a new field (maxAge) to both methods, it's worth noting for consistency. A user passing claimNonce to getAuthorizationUrlWithPKCE would have it silently ignored.

(Refers to lines 1514-1527)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[greptile-apps]

Greptile Summary

This PR adds the OIDC max_age parameter to both getAuthorizationUrl and getAuthorizationUrlWithPKCE, allowing callers to force re-authentication when a user's last login exceeds a given age in seconds. The implementation is clean, follows existing patterns in the codebase, and is backed by test coverage for both methods.

• Interface change (authorization-url-options.interface.ts): adds maxAge?: number with a clear JSDoc comment to UserManagementAuthorizationURLBaseOptions, which is shared by both methods.
• Implementation (user-management.ts): maxAge is destructured and passed as max_age: maxAge?.toString() in both getAuthorizationUrl and getAuthorizationUrlWithPKCE; the optional-chaining correctly omits the parameter when undefined, and max_age=0 (re-authenticate immediately) is handled correctly since 0 is not null/undefined.
• Tests (user-management.spec.ts): one test case per method verifies that max_age=3600 appears in the generated URL.

Confidence Score: 5/5

Safe to merge — the change is additive and isolated to URL generation; no existing behaviour is altered.

The change is a small, additive parameter threaded through two related methods that already follow this exact pattern. The toQueryString utility only skips undefined, so the maxAge?.toString() idiom is correct and max_age=0 works as expected. No auth logic, token handling, or existing flows are modified.

No files require special attention.

Important Files Changed

Filename	Overview
src/user-management/interfaces/authorization-url-options.interface.ts	Adds optional maxAge?: number field to UserManagementAuthorizationURLBaseOptions with a JSDoc comment; clean and well-placed.
src/user-management/user-management.ts	Destructures maxAge and passes it as max_age: maxAge?.toString() in both getAuthorizationUrl and getAuthorizationUrlWithPKCE; follows existing patterns and correctly handles the undefined case via optional chaining.
src/user-management/user-management.spec.ts	Adds one test case per method verifying max_age=3600 appears in the generated URL; coverage is adequate for the happy path.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant App
    participant SDK as WorkOS SDK
    participant Auth as /user_management/authorize

    App->>SDK: "getAuthorizationUrl({ maxAge: 3600, ... })"
    SDK->>SDK: Destructure maxAge
    SDK->>SDK: maxAge?.toString() → "3600"
    SDK->>Auth: "Redirect URL with max_age=3600"
    Auth-->>App: Returns URL string

    App->>SDK: "getAuthorizationUrlWithPKCE({ maxAge: 3600, ... })"
    SDK->>SDK: Generate PKCE (codeChallenge, codeVerifier)
    SDK->>SDK: Generate random state
    SDK->>SDK: maxAge?.toString() → "3600"
    SDK-->>App: "{ url (with max_age=3600), state, codeVerifier }"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant App
    participant SDK as WorkOS SDK
    participant Auth as /user_management/authorize

    App->>SDK: "getAuthorizationUrl({ maxAge: 3600, ... })"
    SDK->>SDK: Destructure maxAge
    SDK->>SDK: maxAge?.toString() → "3600"
    SDK->>Auth: "Redirect URL with max_age=3600"
    Auth-->>App: Returns URL string

    App->>SDK: "getAuthorizationUrlWithPKCE({ maxAge: 3600, ... })"
    SDK->>SDK: Generate PKCE (codeChallenge, codeVerifier)
    SDK->>SDK: Generate random state
    SDK->>SDK: maxAge?.toString() → "3600"
    SDK-->>App: "{ url (with max_age=3600), state, codeVerifier }"

Loading

_{Reviews (5): Last reviewed commit: "feat(user-management): add max_age param..." | Re-trigger Greptile}