​

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

​

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

​

Request Body Parameters

​

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

​

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.