Session Management

Understanding how the Hubble SDK manages sessions is important for handling multi-device scenarios and user logout flows correctly.

How Sessions Work?

Every time the SDK is loaded, it is initiated with a token (the SSO token you pass in the URL). Hubble uses this token to authenticate the user via your SSO endpoint and creates a new session for that user.

Session Duration

By default, an SDK session is valid for 24 hours. After 24 hours, the session expires and the user will need to be re-authenticated via SSO the next time the SDK is opened. This duration can be customized - contact the Hubble team if you need a different session lifetime for your use case.

One Session Per User

A user can have only one active session at a time. If a user opens the SDK on a second device (or a second browser), a new session is created for that device and the session on the earlier device is automatically invalidated.

For example:

1. User opens the SDK on their phone. Session is created on Device A.
2. User later opens the SDK on another device. A new session is created on Device B.
3. The session on Device A is now invalidated. If the user tries to use the SDK on Device A, they will see an error and need to re-initiate the SDK.

You can use the session invalidation API (described below) to handle such scenarios gracefully in your app - for example, detecting the error and automatically re-loading the SDK with a fresh token.

Invalidating Sessions from Your Backend

There are scenarios where your app’s session gets invalidated on your backend (e.g., user logs out, session timeout, security event). In these cases, you may also want to invalidate the user’s Hubble SDK session so that the SDK is no longer accessible. Hubble provides a server-side API for this:

POSThttps://api.myhubble.money/v1/auth/partner/logout-user

Property	Value
Method	POST
URL	https://api.myhubble.money/v1/auth/partner/logout-user
Header	X-PARTNER-SECRET (secret key shared by Hubble)
Content-Type	application/json

Request Body:

{
  "userId": "user-12345"
}

The userId should match the userId your SSO endpoint returns for this user.

Response (200 OK):

{
  "success": true
}

When to Call This API

You should call the session invalidation API in the following scenarios:

1. User logout: Whenever a user logs out of your application, call this API to invalidate their Hubble SDK session as well.
2. Account switching: If your app supports multiple accounts, invalidate the previous user’s SDK session before loading the SDK for the new user.
3. Security events: If a user’s account is compromised or you detect suspicious activity, invalidate their SDK session immediately.

Best Practice: Destroy the WebView on Logout

In addition to calling the session invalidation API, destroy the WebView or iframe when the user logs out. This ensures no cached content from the previous session is visible. When the new user opens the SDK, create a fresh WebView with a new SSO token.

Example: Node.js

const axios = require('axios');

async function invalidateHubbleSession(userId) {
  try {
    const response = await axios.post(
      'https://api.myhubble.money/v1/auth/partner/logout-user',
      { userId },
      {
        headers: {
          'X-PARTNER-SECRET': process.env.HUBBLE_PARTNER_SECRET,
          'Content-Type': 'application/json',
        },
      }
    );
    console.log('Session invalidated:', response.data);
  } catch (error) {
    console.error('Failed to invalidate session:', error.message);
  }
}

// Call when user logs out
invalidateHubbleSession('user-12345');

Example: Python

import requests

def invalidate_hubble_session(user_id: str):
    response = requests.post(
        'https://api.myhubble.money/v1/auth/partner/logout-user',
        json={'userId': user_id},
        headers={
            'X-PARTNER-SECRET': HUBBLE_PARTNER_SECRET,
            'Content-Type': 'application/json',
        },
    )
    response.raise_for_status()
    return response.json()

# Call when user logs out
invalidate_hubble_session('user-12345')