​
Sandbox Authentication

The FinHub Sandbox environment uses a dedicated authentication endpoint for tenant authentication. This document explains how to authenticate with the FinHub Sandbox API services.

​
Overview

FinHub Sandbox authentication uses the /api/v2/auth/sandbox/token endpoint, which requires both user credentials and API client credentials. This authentication method is specific to the sandbox environment.

​
Key Differences Between Sandbox and Production

SandboxProduction
Parameters must be manually added to the requestParameters are automatically provided by the system
Uses /api/v2/auth/sandbox/token endpointUses standard OAuth2 endpoints
Requires both user and client credentialsTypically requires only client credentials
Designed for testing and developmentDesigned for live operations

​
Prerequisites

Before you can authenticate with the FinHub Sandbox APIs, you need:
  1. A sandbox tenant account with FinHub
  2. Sandbox username and password
  3. Client ID and client secret for your sandbox tenant
  4. X-Tenant-ID header value for multi-tenant operations

​
Sandbox Authentication Process

​
Step 1: Request an Access Token

To obtain an access token in the sandbox 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

HeaderDescriptionRequiredExample
Content-TypeMedia type of the request bodyYesapplication/json
sec-ch-ua-platformClient platform informationYesWindows
X-Forwarded-ForClient IP addressYes127.0.0.1
User-AgentClient user agent informationYesMozilla/5.0 (Windows NT 10.0; Win64; x64)
X-Tenant-IDTenant identifier for multi-tenant operationsYes1234567

​
Request Body Parameters

ParameterDescriptionRequiredSource
usernameSandbox usernameYesProvided in welcome email
passwordSandbox passwordYesProvided in welcome email
customerIdClient ID for your sandbox tenantYesDeveloper Portal > API Access
customerSecretClient secret for your sandbox tenantYesDeveloper Portal > API Access
accountTypeType of account (b2b or b2c)YesBased on your integration type

​
Step 2: Receive the Access Token

If the credentials are valid, the authorization server will respond with an access token: 
{
  "access_token": "eyJ4NXQiOiJNVFJsT1RFM1lXRmxNR1JrTlRGa1pUQTNOVFZsTURGa1ltTm1NV1psTkRNM1l6azNOakptWXciLCJraWQiOiJOelF5T0RsaE1EQmhaVFkwWVRCaVl6RXdNVFk...",
  "token_type": "Bearer",
  "expires_in": 10000,
  "scope": "01f0418c-36da-17a0-830a-aca6bf25e007"
}

​
Step 3: Use the Access Token

Include the access token in the Authorization header of all subsequent API requests: 
GET /api/v2/some-endpoint HTTP/1.1
Host: gateway.finhub.cloud
Authorization: Bearer eyJ4NXQiOiJNVFJsT1RFM1lXRmxNR1JrTlRGa1pUQTNOVFZsTURGa1ltTm1NV1psTkRNM1l6azNOakptWXciLCJraWQiOiJOelF5T0RsaE1EQmhaVFkwWVRCaVl6RXdNVFk...
Content-Type: application/json
X-Tenant-ID: 1234567

​
Token Management

​
Token Expiration

The access token has an expiration time specified in the expires_in field of the response (in seconds). Your application should:
  1. Store the token securely
  2. Track the token’s expiration time
  3. Request a new token before the current one expires

​
Token Caching

For optimal performance, your application should cache the token until it nears expiration. A good practice is to refresh the token when it reaches 90% of its lifetime.

​
Code Examples

    ​
    Troubleshooting

    ​
    Common Error Responses

    Status CodeDescriptionPossible CauseSolution
    400Bad RequestInvalid request formatCheck request body format and required fields
    401UnauthorizedInvalid credentialsVerify username, password, client ID, and client secret
    403ForbiddenInsufficient permissionsVerify tenant ID and account permissions
    429Too Many RequestsRate limit exceededImplement exponential backoff and retry strategy
    500Internal Server ErrorServer-side issueContact FinHub support

    ​
    Best Practices

    1. Secure Storage: Never store credentials in client-side code or public repositories
    2. Error Handling: Implement proper error handling for authentication failures
    3. Retry Logic: Use exponential backoff for retries on transient errors
    4. Logging: Log authentication attempts for debugging (but never log credentials)
    5. Token Management: Implement proper token caching and refresh strategies

    ​
    Step 3: Use the Access Token

    Include the access token in the Authorization header of your API requests: 
    GET /api/v2/resource HTTP/1.1
Host: api.finhub.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

    ​
    Token Lifecycle

    • Access tokens are valid for 1 hour (3600 seconds)
    • You should request a new token when the current one expires
    • Do not share tokens between different applications or environments

    ​
    Environment-Specific Authentication

    FinHub provides separate authentication endpoints for each environment:
    • Sandbox: https://auth.sandbox.finhub.com/oauth2/token
    • Production: https://auth.finhub.com/oauth2/token
    Always use the appropriate endpoint for your current environment.

    ​
    Security Best Practices

    1. Secure Storage: Store client secrets securely and never expose them in client-side code
    2. Token Management: Implement proper token caching and refresh mechanisms
    3. TLS/SSL: Always use HTTPS for all API communications
    4. IP Restrictions: Consider restricting API access to specific IP addresses
    5. Minimal Scope: Request only the scopes your application needs

    ​
    Troubleshooting

    Common authentication errors:
    • 401 Unauthorized: Invalid or expired access token
    • 403 Forbidden: Valid token but insufficient permissions
    • 400 Bad Request: Malformed authentication request
    If you encounter persistent authentication issues, contact FinHub Support with your tenant ID and detailed error information.