​
Session Management in the Playground

This guide explains how to manage sessions when working with the FinHub API in the Playground environment.

​
Session Tokens Overview

When a user logs in through the authentication endpoints, the system creates a session and returns several tokens:

{
  "expires_in": 10000,
  "token_type": "Bearer",
  "scope": "01f0418c-36da-17a0-830a-aca6bf25e007",
  "customerId": "12345678-abcd-1234-efgh-1234567890ab",
  "tenantId": "1234567",
  "userSessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Key Session Components

ComponentDescriptionUsage
userSessionTokenJWT token for user session validationUsed for session validation and contains user identity claims
customerIdUnique identifier for the customerReference in customer-related operations
tenantIdIdentifier for the tenantUsed for multi-tenant operations

​
Activity Tracking Headers

Every API request in the FinHub platform must include two important headers for session and activity tracking:

  1. X-Activity-ID: A UUID that identifies a specific user activity or flow
  2. X-Tenant-ID: The tenant identifier for multi-tenant operations

​
Activity ID Generation

The Activity ID should be a UUID (v4) generated for each distinct user activity or flow. For example:

    ​
    Including Session Headers in Requests

    All API requests must include the session token and tracking headers:

      ​
      Session Lifecycle

      ​
      Session Creation

      A session is created when a user successfully authenticates through the login endpoint. The session includes:

      1. A user session token (JWT)
      2. An internally managed access token (not exposed to clients)
      3. User identity information

      ​
      Session Maintenance

      To maintain an active session:

      1. Include the user session token in all API requests
      2. Use consistent activity IDs for related operations within a flow
      3. Re-authenticate before the token expires (based on expires_in value)

      ​
      Session Expiration

      Sessions expire after the time specified in the expires_in parameter (in seconds). When a session expires:

      1. API requests will return a 401 Unauthorized error
      2. You must authenticate again to obtain a new session token
      3. A new activity ID should be generated for the new session

      ​
      Session Termination

      To explicitly terminate a session, call the logout endpoint:

      POST /api/v2/auth/logout HTTP/1.1
Host: gateway.finhub.cloud
Content-Type: application/json
X-Tenant-ID: 1234567
X-Activity-ID: 550e8400-e29b-41d4-a716-446655440000
X-Session-Active: true
X-User-Session-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

      ​
      Best Practices for Session Management

      1. Generate unique activity IDs for each user flow or journey
      2. Store session tokens securely using appropriate storage mechanisms
      3. Implement token refresh logic to handle token expiration
      4. Clear session data after logout or session expiration
      5. Handle authentication errors gracefully with user-friendly messages

      ​
      Moving to Integration

      When you’re ready to move from the Playground to the Integration environment, you’ll need to follow more formal session management practices. See the Integration Session Management guide for details.

      ​
      Important Notes

      • In the Playground environment, session timeouts are typically longer than in production to facilitate development and testing
      • For security reasons, the raw access token is not exposed to clients and is managed internally by the system
      • Detailed session management is part of the formal integration process and will be covered in depth during that phase

      For questions about session management in the Playground environment, contact our developer support team at developer-support@finhub.cloud.