​
Session Management in the Integration Environment

This guide explains how to manage sessions when working with the FinHub API in the Integration environment, which implements production-equivalent session handling.

​
Session Tokens Overview

When a user logs in through the authentication endpoints, the system creates a session and returns several tokens: 
{
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "01f0418c-36da-17a0-830a-aca6bf25e007",
  "customerId": "12345678-abcd-1234-efgh-1234567890ab",
  "tenantId": "1234567",
  "userSessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Key Session Components

ComponentDescriptionUsage
userSessionTokenJWT token for user session validationUsed for session validation and contains user identity claims
refreshTokenToken used to obtain a new session token without re-authenticationUsed when the session token expires
customerIdUnique identifier for the customerReference in customer-related operations
tenantIdIdentifier for the tenantUsed for multi-tenant operations

​
Required Session Headers

Every API request in the FinHub Integration environment must include these headers:
HeaderDescriptionRequiredExample
AuthorizationBearer token for authenticationYesBearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Activity-IDUUID that identifies a specific user activity or flowYes550e8400-e29b-41d4-a716-446655440000
X-Tenant-IDTenant identifier for multi-tenant operationsYes1234567
X-Session-IDOptional session identifier for session trackingNosession-12345678
X-Correlation-IDOptional identifier for request correlationNocorr-12345678

​
Activity ID Generation

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

    ​
    Session Lifecycle Management

    ​
    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. A refresh token for token renewal
    3. An internally managed access token (not exposed to clients)
    4. User identity information

    ​
    Token Refresh

    In the Integration environment, you can refresh an expired token without requiring the user to re-enter credentials:

      ​
      Session Expiration Handling

      To handle session expiration gracefully:
      1. Monitor token expiration: Check the token expiration before making API requests
      2. Implement automatic refresh: Refresh the token when it’s close to expiration
      3. Handle refresh failures: If refresh fails, redirect to the login page

        ​
        Session Termination

        To explicitly terminate a session, call the logout endpoint: 
        POST /api/v2/auth/logout HTTP/1.1
Host: integration.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...

          ​
          Session Security Best Practices

          ​
          Token Storage

          Store tokens securely based on your platform:
          PlatformRecommended StorageNot Recommended
          Web BrowserHttpOnly cookies, Session StorageLocal Storage, JavaScript variables
          Mobile AppsSecure Keychain (iOS), Keystore (Android)SharedPreferences, UserDefaults
          Server-sideEncrypted database, RedisEnvironment variables, config files

          ​
          Token Transmission

          • Always use HTTPS for all API requests
          • Use Bearer authentication scheme in the Authorization header
          • Never include tokens in URLs or query parameters
          • Implement CSRF protection for web applications

          ​
          Session Monitoring

          • Implement session activity logging
          • Monitor for suspicious session activities
          • Set up alerts for unusual session patterns
          • Implement rate limiting for authentication endpoints

          ​
          Differences from Playground

          FeaturePlaygroundIntegration
          Token ExpirationLonger (10000s)Standard (3600s)
          Refresh TokenNot providedProvided
          Session HeadersBasicComprehensive
          Security RequirementsLenientStrict

          ​
          Moving to Production

          When you’re ready to move from the Integration to the Production environment, you’ll need to implement additional session security measures. See the Production Session Management guide for details.

          ​
          Playground Reference

          For simplified testing and experimentation, you can always return to the Playground Session Management guide.

          ​
          Need Integration Support?

          If you encounter any issues with session management in the Integration environment, please contact our integration support team at integration-support@finhub.cloud.