​
Finhub Playground

The FinHub Playground allows you to explore and test the FinHub APIs in a safe sandbox environment. This guide walks you through the key steps to get started with the playground.

​
Getting Started

Before you begin exploring the APIs, you need to authenticate your sandbox tenant. The playground provides a comprehensive environment to test all FinHub API capabilities without affecting real data or transactions.

​
Tenant Sandbox Login

The first step in using the playground is authenticating your sandbox tenant. This process uses OAuth 2.0 Client Credentials flow to obtain an access token.

​
API Endpoint

POST /api/v2/auth/sandbox/token

​
Required Headers

NameDescriptionExample
sec-ch-ua-platformClient platform informationWindows
X-Forwarded-ForClient IP address127.0.0.1
User-AgentClient user agent informationMozilla/5.0 (Windows NT 10.0; Win64; x64)
X-Tenant-IDTenant identifier for multi-tenant operations1234567
Content-TypeMedia type of the request bodyapplication/json

​
Request Body

{
  "username": "test",
  "password": "test123",
  "customerId": "OQ1GG9iFxVcgzforkJR8CImHiuwa",
  "customerSecret": "lPGwgaAENdwLxtfuqQu5R606jswa",
  "accountType": "b2b"
}

​
Field Descriptions

FieldDescriptionHow to Obtain
usernameYour sandbox usernameProvided in the welcome email after sandbox activation
passwordYour sandbox passwordProvided in the welcome email after sandbox activation
customerIdYour client IDAvailable in the Developer Portal under API Access
customerSecretYour client secretAvailable in the Developer Portal under API Access
accountTypeType of account (b2b or b2c)Depends on your integration type

​
Response

A successful authentication will return an OAuth 2.0 token response: 
{
  "access_token": "eyJ4NXQiOiJNVFJsT1RFM1lXRmxNR1JrTlRGa1pUQTNOVFZsTURGa1ltTm1NV1psTkRNM1l6azNOakptWXciLCJraWQiOiJOelF5T0RsaE1EQmhaVFkwWVRCaVl6RXdNVFk...",
  "scope": "01f0418c-36da-17a0-830a-aca6bf25e007",
  "token_type": "Bearer",
  "expires_in": 10000
}

    ​
    Token Usage

    After obtaining the access token, include it in the Authorization header of all subsequent API requests: 
    Authorization: Bearer eyJ4NXQiOiJNVFJsT1RFM1lXRmxNR1JrTlRGa1pUQTNOVFZsTURGa1ltTm1NV1psTkRNM1l6azNOakptWXciLCJraWQiOiJOelF5T0RsaE1EQmhaVFkwWVRCaVl6RXdNVFk...

    ​
    Available Sandbox Clients

    The sandbox environment provides pre-configured client accounts for testing. You can retrieve the list of available sandbox clients using the following endpoint: 
    GET /api/v2/test/sandbox-clients
    This will return a list of available sandbox client names that you can use for testing.

    ​
    Playground Features

    The FinHub Playground offers several features to help you test and develop your integration:

    ​
    1. API Explorer

    Browse and test all available API endpoints directly from the Developer Portal. The API Explorer provides:
    • Interactive documentation
    • Request builders
    • Response viewers
    • Code samples in multiple languages

    ​
    2. Test Data Generation

    Generate test data for various scenarios:
    • Create test customers
    • Generate test transactions
    • Simulate different financial events

    ​
    3. Webhook Testing

    Test webhook integrations by:
    • Triggering test events
    • Viewing webhook payloads
    • Verifying webhook signatures

    ​
    4. Error Simulation

    Simulate various error conditions to test your error handling:
    • Authentication failures
    • Validation errors
    • Business rule violations
    • System errors

    ​
    Playground Limitations

    While the playground provides a comprehensive testing environment, be aware of these limitations:
    • Daily transaction limits
    • Simulated external integrations
    • Periodic data resets
    • Limited historical data

    ​
    Best Practices for Playground Testing

    1. Start Simple: Begin with basic API calls before moving to complex scenarios
    2. Test Error Handling: Deliberately trigger errors to test your error handling
    3. Use Test Accounts: Don’t use real customer data in the sandbox
    4. Monitor Rate Limits: Be aware of API rate limits in the sandbox
    5. Keep Tokens Secure: Even in the sandbox, practice good security by not exposing tokens

    ​
    Next Steps