​

Production Environment Authentication

This guide explains how to authenticate with the FinHub API in the Production environment, which implements enterprise-grade security measures for live financial transactions.

​

Overview

The Production environment implements a comprehensive OAuth2 authentication flow with certificate-based mutual TLS authentication. This ensures maximum security for all financial transactions and sensitive data.

​

Prerequisites

Before you can authenticate with the FinHub Production APIs, you need:

1. A production tenant account with FinHub
2. Production environment credentials (username and password)
3. Client ID and client secret for your production tenant
4. X-Tenant-ID header value for multi-tenant operations
5. Client certificates for mutual TLS authentication (required)
6. Whitelisted IP addresses for your API clients

​

Certificate Requirements

​

Client Certificate

You must obtain a client certificate from FinHub or a trusted Certificate Authority (CA) that meets these requirements:

• X.509 v3 certificate
• 2048-bit RSA key or stronger
• SHA-256 signature algorithm
• Maximum validity period of 1 year
• Subject containing your organization’s details
• Extended Key Usage for Client Authentication (1.3.6.1.5.5.7.3.2)

​

Certificate Installation

Install your client certificate according to your platform:

​

Authentication Process

​

Step 1: Request Authentication

To authenticate in the production environment, make a POST request to the production token endpoint using mutual TLS:

POST /api/v2/auth/token HTTP/1.1
Host: api.finhub.cloud
Content-Type: application/json
sec-ch-ua-platform: Windows
X-Forwarded-For: 127.0.0.1
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
X-Tenant-ID: 1234567

{
  "username": "production_user",
  "password": "production_password",
  "customerId": "OQ1GG9iFxVcgzforkJR8CImHiuwa",
  "customerSecret": "lPGwgaAENdwLxtfuqQu5R606jswa",
  "accountType": "b2b",
  "grantType": "password"
}

​

Request Headers

​

Request Body Parameters

​

Step 2: Receive the Authentication Response

If the credentials and certificate are valid, the authorization server will respond with authentication information:

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

​

Response Parameters

​

Step 3: Use the Session Token for API Requests

Include the required headers in all subsequent API requests. The API Clients’ BFF or production environment will handle authentication internally using your session token:

GET /api/v2/some-endpoint HTTP/1.1
Host: api.finhub.cloud
Content-Type: application/json
X-Tenant-ID: 1234567
X-Activity-ID: 550e8400-e29b-41d4-a716-446655440000
X-Request-ID: 123e4567-e89b-12d3-a456-426614174000
X-Session-Active: true
X-User-Session-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Important Note: When you authenticate, the system generates an access token internally that is used to access backend services. This token has an expiration time specified by the expires_in parameter. If your API requests start receiving 401 Unauthorized errors with a message indicating that the access token has expired, you will need to authenticate again to obtain a new token. The access token is managed by the system and is not directly exposed to clients for security reasons.

​

Token Refresh

In the Production environment, you can refresh an existing token without requiring the user to re-enter credentials. The process requires authentication with the current token and uses the internal token key extracted from the JWT token:

POST /api/v2/auth/token/refresh HTTP/1.1
Host: api.finhub.cloud
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Tenant-ID: 1234567
X-Session-Active: true
X-User-Session-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "userSessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "internalTokenKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Note: The internalTokenKey is extracted from the claims in the JWT token (userSessionToken). This key is used by the API Clients’ BFF to identify and refresh the associated access token without requiring client credentials to be sent in the request. If the token has more than 10% of its validity time remaining, it will not be refreshed and the current validity will be provided in the response.

Security: Token refresh requires authentication with a valid session token. The user in the authenticated session must match the user associated with the token being refreshed.

​

Security Considerations

​

Certificate Management

• Certificate Rotation: Implement certificate rotation procedures before expiration
• Private Key Protection: Store private keys in a Hardware Security Module (HSM) or secure key vault
• Certificate Revocation: Have procedures in place for certificate revocation in case of compromise

​

IP Restrictions

• Maintain a list of whitelisted IP addresses for API access
• Notify FinHub in advance of any IP address changes
• Implement IP-based access controls on your side as well

​

Token Security

• Store tokens in secure, encrypted storage
• Implement token revocation on user logout or suspicious activity
• Never log or expose tokens in client-side code

​

Differences from Integration

​

Integration Reference

For testing and validation before production deployment, refer to the Integration Authentication.

​

Playground Reference

For simplified testing and experimentation, you can always return to the Playground Authentication.

​

Troubleshooting

​

Common Authentication Errors

If you encounter persistent authentication issues, contact FinHub Production Support with your tenant ID and detailed error information.