bknd-session-handling_skill

Overview

This skill helps manage user sessions in Bknd applications by covering JWT lifecycle, session persistence, automatic renewal, and expiration handling. It explains cookie vs header transport, practical code patterns for frontend and server, and integration tips for React apps. Use it to implement reliable auth state checks, graceful expiration flows, and secure token handling.

How this skill works

It inspects how Bknd issues stateless JWTs on login, where tokens can be stored (httpOnly cookies, localStorage, sessionStorage, or memory), and how tokens are validated on each request. The skill describes cookie auto-renewal behavior, manual header-based refresh strategies, and patterns to detect and handle expired tokens. It also covers server-side request validation using Bknd APIs.

When to use it

• Implementing session persistence and restore on app start
• Choosing cookie vs header transport for security or manual control
• Handling token expiration and prompting re-authentication
• Auto-refreshing or periodically validating cookie-based sessions
• Validating sessions server-side in API routes

Best practices

• Prefer httpOnly, secure cookies for browsers to mitigate XSS when possible
• Match cookie expiry with JWT expiry and enable cookie.renew for activity-based extension
• Use localStorage or sessionStorage only when you need manual header transport; protect against XSS
• Check session on app mount (api.auth.me()) and notify app state via a session manager or provider
• Schedule proactive refresh for header tokens based on decoded exp, and show re-login UI before expiry

Example use cases

• A React app that restores user on mount using a SessionProvider and api.auth.me()
• Server API route that calls api.auth.resolveAuthFromRequest to gate endpoints
• Single-page app using cookie transport to rely on auto-renew and avoid manual token handling
• Header-based client that decodes JWT exp to schedule a re-authentication prompt
• Background task that checks session on window focus and redirects to login if expired