Authentication
Authentication for FinHub API Sandbox Integration
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
Sandbox | Production |
---|---|
Parameters must be manually added to the request | Parameters are automatically provided by the system |
Uses /api/v2/auth/sandbox/token endpoint | Uses standard OAuth2 endpoints |
Requires both user and client credentials | Typically requires only client credentials |
Designed for testing and development | Designed for live operations |
Prerequisites
Before you can authenticate with the FinHub Sandbox 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
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:
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 | Developer Portal > API Access |
customerSecret | Client secret for your sandbox tenant | Yes | Developer Portal > API Access |
accountType | Type of account (b2b or b2c) | Yes | Based on your integration type |
Step 2: Receive the Access Token
If the credentials are valid, the authorization server will respond with an access token:
Step 3: Use the Access Token
Include the access token in the Authorization
header of all subsequent API requests:
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:
- Store the token securely
- Track the token’s expiration time
- 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 Code | Description | Possible Cause | Solution |
---|---|---|---|
400 | Bad Request | Invalid request format | Check request body format and required fields |
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 | Implement exponential backoff and retry strategy |
500 | Internal Server Error | Server-side issue | Contact FinHub support |
Best Practices
- Secure Storage: Never store credentials in client-side code or public repositories
- Error Handling: Implement proper error handling for authentication failures
- Retry Logic: Use exponential backoff for retries on transient errors
- Logging: Log authentication attempts for debugging (but never log credentials)
- 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:
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
- Secure Storage: Store client secrets securely and never expose them in client-side code
- Token Management: Implement proper token caching and refresh mechanisms
- TLS/SSL: Always use HTTPS for all API communications
- IP Restrictions: Consider restricting API access to specific IP addresses
- 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.