Playground Authentication

This guide explains how to authenticate with the FinHub API in the Playground environment.

Overview

The Playground environment uses a dedicated authentication endpoint for tenant authentication. This simplified process is designed for development and testing purposes.

Environment Differences

Playground Environment:

Uses sandbox login with customerId and customerSecret sent directly in the request
These credentials are provided in the sandbox activation email
Designed for quick experimentation without complex setup

Integration & Production Environments:

Use standard username/password authentication
Client credentials (customer ID/secret) are pre-configured during onboarding
Require more secure authentication methods including mutual TLS in production

Prerequisites

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

A sandbox tenant account with FinHub
Sandbox username and password
Client ID and client secret for your sandbox tenant
X-Tenant-ID header value for multi-tenant operations

Authentication Process

Step 1: Request Authentication

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

POST /api/v2/auth/sandbox/token HTTP/1.1
Host: gateway.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": "test",
  "password": "test123",
  "customerId": "OQ1GG9iFxVcgzforkJR8CImHiuwa",
  "customerSecret": "lPGwgaAENdwLxtfuqQu5R606jswa",
  "accountType": "b2b"
}

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	Sandbox username	Yes	Provided in welcome email
password	Sandbox password	Yes	Provided in welcome email
customerId	Client ID for your sandbox tenant	Yes	Provided in sandbox activation email
customerSecret	Client secret for your sandbox tenant	Yes	Provided in sandbox activation email
accountType	Type of account (b2b or b2c)	Yes	Based on your integration type

Important: The customerId and customerSecret are only sent directly in requests in the Playground environment. In Integration and Production environments, these credentials are securely configured during onboarding and not included in API requests.

Step 2: Receive the Authentication Response

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

{
  "expires_in": 10000,
  "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.

Step 3: Use the Session Token for API Requests

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

GET /api/v2/some-endpoint HTTP/1.1
Host: gateway.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 Playground 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: playground.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

Moving to Integration

When you’re ready to move from the Playground to the Integration environment, you’ll need to follow a more formal authentication process. See the Integration Authentication guide for details.

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

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

Headers

X-Tenant-ID

string

required

Tenant identifier

Example:

"1234567"

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

Sandbox login credentials

The body is of type object.

Response

200

application/json

Authentication successful

The response is of type object.

About FinHub

​Playground 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

​Moving to Integration

​Troubleshooting

​Common Authentication Errors

Headers

Body

Response

Playground 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

Moving to Integration

Troubleshooting

Common Authentication Errors