# 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](https://docs.byo.propelauth.com/sessions/reference#validate-session) function, use [Validate and Refresh](https://docs.byo.propelauth.com/sessions/reference#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

```javascript
// 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);
}
```

```python
# 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)
```

```go
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})
}
```

```java
// 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);
}
```

```csharp
// 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](https://docs.byo.propelauth.com/sessions/features/tags), [device registration](https://docs.byo.propelauth.com/sessions/features/new-device-notifications), and [theft protection](https://docs.byo.propelauth.com/sessions/features/theft-protection).