​

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

​

Required Session Headers

Every API request in the FinHub Integration environment must include these headers:

​

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:

​

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

​

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.