Sessions

Managing user sessions.

Overview

Sessions contain comprehensive application data, functioning like a dynamic configuration file (unique for every user) that includes account settings, user preferences, access controls, and other essential information needed to effectively serve the application.

Once authenticated, these sessions can be cached locally and remain valid until the API explicitly signals a need for refresh through the X-Session-Status header. This approach eliminates the need for arbitrary session expiration times or unnecessary refresh calls, as the API will notify you when the session data needs updating.

Requesting sessions

You can request a session at any time using the /app/session endpoint. Post-authentication sessions are cached on the server and are automatically refreshed when needed, so the response times fast, but not as fast as not making a request at all.

You can cache the sessions locally and refresh them when notified by the API through the X-Session-Status header. This approach eliminates the need for arbitrary session expiration times or unnecessary refresh calls, as the API will notify you when the session data needs updating.

Session status

An X-Session-Status header is included in every API response.

HTTP/1.1 200 OK
...
X-Session-Status: current
...

The value indicates the current state of the session:

• auth - Session is in the authentication stage
• current - Session data is up to date
• stale - Session should be refreshed as underlying data has changed

Handling session status

You can inspect the X-Session-Status header on the client side and take appropriate action — even before executing your main request. Here's how you might handle this:

// sessionManager.js
const handleSessionStatus = (response) => {
    const sessionStatus = response.headers.get('X-Session-Status');

    switch (sessionStatus) {
        case 'auth':
            // Proceed normlly
            return response.json();
            break;
            
        case 'auth.login-account':
            window.location.href = '/login-account';
            break;

        case 'current':
            // Proceed normally
            return response.json();
            break;

        case 'stale':
            // Refresh session, store the data, and retry original request
            return fetch('https://api.backstack.com/app/session')
                .then(response => response.json())
                .then(data => {
                    localStorage.setItem('sessionData', JSON.stringify(data));
                    return fetch(response.url);
                });
            
        default:
            throw new Error(`Unknown session status: ${sessionStatus}`);
    }
};

// Example usage in an API call
const fetchData = async () => {
    try {
        const response = await fetch('https://api.backstack.com/some-endpoint');
        return handleSessionStatus(response);
    } catch (error) {
        console.error('Error fetching data:', error);
    }
};

Related information

• Requests - Making requests to the API.
• Responses - Handling responses from the API.
• Authentication - Authenticating users.