Integration Environment Authentication

This guide explains how to authenticate with the FinHub API in the Integration environment, which uses production-equivalent OAuth2 flows.

Overview

The Integration environment implements the full OAuth2 authentication flow with enhanced security requirements to prepare you for production deployment. This includes certificate validation, stricter token handling, and more comprehensive error responses.

Environment Differences

Integration Environment vs. Playground:

Unlike the Playground environment, client credentials (customerId and customerSecret) are pre-configured during onboarding
These credentials are not sent in API requests but are securely stored and configured in the Sandbox Backend
Authentication uses standard username/password flow similar to production
The Integration environment is designed to closely mirror the production security model

Prerequisites

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

An integration tenant account with FinHub
Integration environment credentials (username and password)
Client ID and client secret for your integration tenant
X-Tenant-ID header value for multi-tenant operations
Client certificates for mutual TLS authentication (if required)

Authentication Process

Step 1: Request Authentication

To authenticate in the integration environment, make a POST request to the integration token endpoint:

POST /api/v2/auth/token HTTP/1.1
Host: integration.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": "integration_user",
  "password": "integration_password",
  "accountType": "b2b",
  "grantType": "password"
}

Note: Unlike the Playground environment, client credentials (customerId and customerSecret) are not included in the request body as they are pre-configured during onboarding.

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	Integration username	Yes	Provided in integration onboarding
password	Integration password	Yes	Provided in integration onboarding
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

Important: Client credentials (customerId and customerSecret) are securely configured during the integration onboarding process and are not included in API requests. These credentials are only shared with authorized company representatives and are used internally by the Sandbox Backend to authenticate with the API Gateway.

Step 2: Receive the Authentication Response

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

{
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "01f0418c-36da-17a0-830a-aca6bf25e007",
  "customerId": "12345678-abcd-1234-efgh-1234567890ab",
  "tenantId": "1234567",
  "userSessionToken": "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

Note: The JWT token (userSessionToken) contains an internal cache key that the Sandbox Backend uses to retrieve and cache the actual Bearer token for API Gateway requests. This internal mechanism is transparent to clients and ensures that access tokens are never exposed directly. In the Integration environment, this key is linked to the pre-configured client credentials established during onboarding.

Step 3: Use the Session Token for API Requests

Include the required headers in all subsequent API requests. The Sandbox Backend or integration environment will handle authentication internally using your session token:

GET /api/v2/some-endpoint 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...

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 Integration 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: integration.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 Sandbox Backend 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.

Code Examples

Security Considerations

Certificate Validation

In the Integration environment, server certificate validation is mandatory. Your client must validate the server’s SSL certificate against trusted certificate authorities.

IP Restrictions

The Integration environment may have IP restrictions. Ensure your client’s IP address is whitelisted for access.

Token Security

Store tokens securely and never expose them in client-side code or logs. Use secure storage mechanisms appropriate for your platform.

Differences from Playground

Feature	Playground	Integration
Token Expiration	Longer (10000s)	Standard (3600s)
Grant Types	Limited	Full OAuth2 support
Error Responses	Basic	Detailed with error codes
Certificate Validation	Optional	Required
Token Refresh	Not supported	Supported

Moving to Production

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

Playground Reference

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

Troubleshooting

Common Authentication Errors

Error Code	Description	Solution
401 Unauthorized	Invalid credentials	Verify username, password, client ID, and client secret
403 Forbidden	Insufficient permissions	Verify tenant ID and account 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 Integration Support with your tenant ID and detailed error information.

Headers

sec-ch-ua-platform

string

Client platform information

Example:

"Windows"

X-Forwarded-For

string

Client IP address

Example:

"192.168.1.1"

Body

application/json

User credentials

The body is of type object.

Response

200

application/json

Authentication successful

The response is of type object.

About FinHub

Integration Authentication

Integration Environment Authentication

Overview

Environment Differences

Prerequisites

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

Code Examples

Security Considerations

Certificate Validation

IP Restrictions

Token Security

Differences from Playground

Moving to Production

Playground Reference

Troubleshooting

Common Authentication Errors

Headers

Body

Response

About FinHub

​Integration Environment Authentication

​Overview

​Environment Differences

​Prerequisites

​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

​Code Examples

​Security Considerations

​Certificate Validation

​IP Restrictions

​Token Security

​Differences from Playground

​Moving to Production

​Playground Reference

​Troubleshooting

​Common Authentication Errors

Headers

Body

Response

Integration Environment Authentication

Overview

Environment Differences

Prerequisites

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

Code Examples

Security Considerations

Certificate Validation

IP Restrictions

Token Security

Differences from Playground

Moving to Production

Playground Reference

Troubleshooting

Common Authentication Errors