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:

A production tenant account with FinHub
Production environment credentials (username and password)
Client ID and client secret for your production tenant
X-Tenant-ID header value for multi-tenant operations
Client certificates for mutual TLS authentication (required)
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

Header	Description	Required	Example
Content-Type	Media type of the request body	Yes	`application/json`
sec-ch-ua-platform	Client platform information	Yes	`Windows`
X-Forwarded-For	Client IP address	Yes	`127.0.0.1`
User-Agent	Client user agent information	Yes	`Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
X-Tenant-ID	Tenant identifier for multi-tenant operations	Yes	`1234567`

Request Body Parameters

Parameter	Description	Required	Source
username	Production username	Yes	Provided in production onboarding
password	Production password	Yes	Provided in production onboarding
customerId	Client ID for your production tenant	Yes	Developer Portal > API Access
customerSecret	Client secret for your production tenant	Yes	Developer Portal > API Access
accountType	Type of account (b2b or b2c)	Yes	Based on your integration type
grantType	OAuth2 grant type (password, client_credentials, etc.)	Yes	Based on your integration flow

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

Parameter	Description	Usage
expires_in	Token expiration time in seconds	Use to determine when to refresh authentication
token_type	Type of token (always “Bearer”)	Required for Authorization header format
scope	Scope of access granted	Identifies the permissions granted
customerId	Unique identifier for the customer	Reference in customer-related operations
tenantId	Identifier for the tenant	Used for multi-tenant operations
userSessionToken	JWT token for user session validation	Used for session validation and contains user identity claims
refreshToken	Token used to obtain a new session token without re-authentication	Used when the session token expires

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

Feature	Integration	Production
Token Expiration	Standard (3600s)	Shorter (1800s)
Certificate Requirements	Optional	Mandatory
IP Restrictions	Limited	Strict
Error Responses	Detailed	Detailed with audit logging
Rate Limiting	Moderate	Strict

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

Error Code	Description	Solution
401 Unauthorized	Invalid credentials	Verify username, password, client ID, and client secret
403 Forbidden	Insufficient permissions or invalid certificate	Verify certificate and permissions
429 Too Many Requests	Rate limit exceeded	Reduce authentication frequency
400 Bad Request	Invalid request format	Check request format and parameters
500 Internal Server Error	Server-side error	Contact support with error details

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

About FinHub

Production Authentication

Production Environment Authentication

Overview

Prerequisites

Certificate Requirements

Client Certificate

Certificate Installation

Authentication Process

Step 1: Request Authentication

Request Headers

Request Body Parameters

Step 2: Receive the Authentication Response

Response Parameters

Step 3: Use the Session Token for API Requests

Token Refresh

Security Considerations

Certificate Management

IP Restrictions

Token Security

Differences from Integration

Integration Reference

Playground Reference

Troubleshooting

Common Authentication Errors

About FinHub

​Production Environment Authentication

​Overview

​Prerequisites

​Certificate Requirements

​Client Certificate

​Certificate Installation

​Authentication Process

​Step 1: Request Authentication

​Request Headers

​Request Body Parameters

​Step 2: Receive the Authentication Response

​Response Parameters

​Step 3: Use the Session Token for API Requests

​Token Refresh

​Security Considerations

​Certificate Management

​IP Restrictions

​Token Security

​Differences from Integration

​Integration Reference

​Playground Reference

​Troubleshooting

​Common Authentication Errors

Production Environment Authentication

Overview

Prerequisites

Certificate Requirements

Client Certificate

Certificate Installation

Authentication Process

Step 1: Request Authentication

Request Headers

Request Body Parameters

Step 2: Receive the Authentication Response

Response Parameters

Step 3: Use the Session Token for API Requests

Token Refresh

Security Considerations

Certificate Management

IP Restrictions

Token Security

Differences from Integration

Integration Reference

Playground Reference

Troubleshooting

Common Authentication Errors