Session Rotation

Session rotation is a simple security feature: it automatically gives users new session tokens periodically. If a token gets stolen, it’s only valid for a limited time instead of the full session duration.

Instead of using the standard Validate Session function, use Validate and Refresh. It does the exact same validation, but sometimes returns a new session token too.

Basic Usage

Here’s the only change you need to make:

Node Python Go Java .NET

// Before: Standard validation
const validation = await client.session.validate({
    sessionToken: req.cookies.sessionToken,
});

// After: Validation with rotation
const validation = await client.session.validateAndRefresh({
    sessionToken: req.cookies.sessionToken,
});

if (validation.ok && validation.data.newSessionToken) {
    // Update the cookie with the new token
    res.cookie("sessionToken", validation.data.newSessionToken, COOKIE_OPTIONS);
}

# Before: Standard validation
validation = await client.session.validate(
    session_token=request.cookies.get("sessionToken")
)

# After: Validation with rotation
validation = await client.session.validate_and_refresh(
    session_token=request.cookies.get("sessionToken")
)

if is_ok(validation) and validation.data.new_session_token:
    # Update the cookie with the new token
    response.set_cookie("sessionToken", validation.data.new_session_token, **COOKIE_OPTIONS)

cookie, _ := r.Cookie("sessionToken")

// Before: Standard validation
validation, err := client.Session.Validate(ctx, byo.ValidateSessionCommand{
    SessionToken: byo.String(cookie.Value),
})

// After: Validation with rotation
refreshed, err := client.Session.ValidateAndRefresh(ctx, byo.ValidateAndRefreshSessionCommand{
    SessionToken: byo.String(cookie.Value),
})

if err == nil && refreshed.NewSessionToken != nil {
    // Update the cookie with the new token
    http.SetCookie(w, &http.Cookie{Name: "sessionToken", Value: *refreshed.NewSessionToken})
}

// Before: Standard validation
ValidateSessionResponse validation = client.session.validate(
    ValidateSessionCommand.builder()
        .sessionToken(sessionToken)
        .build()
);

// After: Validation with rotation
ValidateAndRefreshSessionResponse validation = client.session.validateAndRefresh(
    ValidateAndRefreshSessionCommand.builder()
        .sessionToken(sessionToken)
        .build()
);

if (validation.getNewSessionToken() != null) {
    // Update the cookie with the new token
    Cookie cookie = new Cookie("sessionToken", validation.getNewSessionToken());
    // Set additional cookie options as needed
    response.addCookie(cookie);
}

// Before: Standard validation
var validation = await client.Session.ValidateAsync(new ValidateSessionCommand
{
    SessionToken = sessionToken
});

// After: Validation with rotation
var validation = await client.Session.ValidateAndRefreshAsync(new ValidateAndRefreshSessionCommand
{
    SessionToken = sessionToken
});

if (validation.NewSessionToken != null)
{
    // Update the cookie with the new token
    Response.Cookies.Append("sessionToken", validation.NewSessionToken, COOKIE_OPTIONS);
}

That’s it. The rest of your code stays exactly the same - you still get the same user data and error handling.

When do you get a new Session Token?

PropelAuth BYO only issues a new session token when:

• The current session is still valid
• Enough time has passed since the last rotation (controlled by session_refresh_interval_secs)

This prevents clients from spamming requests to get new tokens. If your refresh interval is 5 minutes, you’ll only get a new token once every 5 minutes, no matter how many times you call validateAndRefresh.

When a new token is issued, PropelAuth BYO handles the transition gracefully to avoid breaking concurrent requests. The system ensures a smooth handover between the old and new token.

Configuration

Control how often tokens rotate with one setting in your session_config.jsonc:

{
    "session_refresh_interval_secs": 300 // 5 minutes
}

When to Use Session Rotation

Use session rotation when:

• You need extra security (financial apps, admin panels)
• You’re already using sessions and want a simple security boost
• Compliance requires limiting token lifetimes

Session rotation is one more layer in your security stack. It works great alongside other session features like tags, device registration, and theft protection.