​

Authentication

All FinHub APIs use OAuth 2.0 for authentication and authorization. This document explains how to authenticate with the FinHub API services.

​

Overview

FinHub uses the OAuth 2.0 Client Credentials flow for tenant authentication. This flow is designed for server-to-server API calls where the tenant application acts on its own behalf rather than on behalf of a specific user.

​

Prerequisites

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

1. A tenant account with FinHub
2. Client credentials (client ID and client secret) provided during the tenant onboarding process
3. Appropriate capability codes (SCT01, SCT02, etc.) enabled for your tenant account

​

OAuth 2.0 Client Credentials Flow

​

Step 1: Request an Access Token

To obtain an access token, make a POST request to the token endpoint:

POST /oauth2/token HTTP/1.1
Host: auth.finhub.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=api

​

Step 2: Receive the Access Token

If the credentials are valid, the authorization server will respond with an access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api"
}

​

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.