Skip to main content
POST
https://sandbox.finhub.cloud
/
api
/
v2.1
/
admin
/
organization
/
{organizationId}
/
users
/
{userId}
/
sessions
Authentication
curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/admin/organization/{organizationId}/users/{userId}/sessions \
  --header 'Content-Type: <content-type>' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --data '
{
  "username": "<string>",
  "password": "<string>",
  "tenantKey": "<string>",
  "tenantSecret": "<string>"
}
'
{
  "code": 200,
  "message": "Success",
  "data": {
    "sessionId": "ed8e1ef7-d885-4753-88ad-afc5aedfac7b",
    "userId": "e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlMmYzYTRiNS1jNmQ3LTQ4ZTktMGYxYS0yYjNjNGQ1ZTZmN2EiLCJvcmdJZCI6ImYzYTRiNWM2LWQ3ZTgtNDlmMC0xYTJiLTNjNGQ1ZTZmN2E4YiIsInRlbmFudElkIjoiZDFlMmYzYTQtYjVjNi00N2Q4LTllMGYtMWEyYjNjNGQ1ZTZmIiwicm9sZXMiOlsiQURNSU4iXSwiaWF0IjoxNzY4MjQ1NzIwLCJleHAiOjE3NjgyNDkzMjB9.signature",
    "refreshToken": "3c68d5a6-d567-4ec7-88df-c8df22ff6151-refresh-token-long-string",
    "expiresAt": "2026-01-13T22:21:48.9745432",
    "success": true,
    "message": "Session created successfully"
  }
}

​
Authentication

FinHub API v2.1 uses admin session-based authentication with JWT Bearer tokens.
Authentication Method: Admin Session ManagementSee Admin Session Management for complete documentation.

​
Authentication Flow

1

Get Tenant Credentials

Obtain Organization ID, User ID, Tenant Key, and Tenant Secret from the Admin Portal
2

Create Admin Session

Call the admin session endpoint with your credentials
3

Use Token

Include the access token in all API requests
4

Refresh Token

Use refresh token before session expires

​
Create Admin Session

​
Endpoint

POST /api/v2.1/admin/organization/{organizationId}/users/{userId}/sessions

​
Path Parameters

​
organizationId
string
required
Your organization UUIDExample: f3a4b5c6-d7e8-49f0-1a2b-3c4d5e6f7a8b
​
userId
string
required
Your admin user UUIDExample: e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a

​
Headers

​
X-Tenant-ID
string
required
Your tenant identifierExample: tenant_cloudvault
​
Content-Type
string
required
Must be application/json

​
Request Body

​
username
string
required
Your admin username or emailExample: [email protected]
​
password
string
required
Your admin password
​
tenantKey
string
required
Your tenant API keyExample: cvK_9XDw5g_Y_8aUtRQgPyX4aTBbObtain from Admin Portal → API Settings
​
tenantSecret
string
required
Your tenant API secretObtain from Admin Portal → API Settings
Keep this secret secure! Never expose in client-side code.

​
Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/admin/organization/f3a4b5c6-d7e8-49f0-1a2b-3c4d5e6f7a8b/users/e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a/sessions" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "your_secure_password",
    "tenantKey": "cvK_9XDw5g_Y_8aUtRQgPyX4aTBb",
    "tenantSecret": "your_tenant_secret"
  }'

​
Response

{
  "code": 200,
  "message": "Success",
  "data": {
    "sessionId": "ed8e1ef7-d885-4753-88ad-afc5aedfac7b",
    "userId": "e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlMmYzYTRiNS1jNmQ3LTQ4ZTktMGYxYS0yYjNjNGQ1ZTZmN2EiLCJvcmdJZCI6ImYzYTRiNWM2LWQ3ZTgtNDlmMC0xYTJiLTNjNGQ1ZTZmN2E4YiIsInRlbmFudElkIjoiZDFlMmYzYTQtYjVjNi00N2Q4LTllMGYtMWEyYjNjNGQ1ZTZmIiwicm9sZXMiOlsiQURNSU4iXSwiaWF0IjoxNzY4MjQ1NzIwLCJleHAiOjE3NjgyNDkzMjB9.signature",
    "refreshToken": "3c68d5a6-d567-4ec7-88df-c8df22ff6151-refresh-token-long-string",
    "expiresAt": "2026-01-13T22:21:48.9745432",
    "success": true,
    "message": "Session created successfully"
  }
}

​
Using the Token

Include the access token in all subsequent API requests: 
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/individual/categorization/hierarchy/d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: tenant_cloudvault"

​
Session Lifecycle

Sessions expire after approximately 1 hour from creation. Use the refresh token to extend the session.
StageDurationAction
Active~60 minutesUse token normally
Near Expiry< 5 minutesRefresh session
ExpiredAfter expiresAtRe-authenticate

​
Refresh Token

To refresh an active session: 
POST /api/v2.1/admin/sessions/{sessionId}/refresh
Authorization: Bearer {current_token}
X-Tenant-ID: {tenant_id}

{
  "refreshToken": "3c68d5a6-d567-4ec7-88df-c8df22ff6151..."
}

​
Security Best Practices

Critical Security Requirements:
  1. Never expose tenant secret or client secret in client-side code
  2. Never commit credentials to version control
  3. Always use HTTPS for all API calls
  4. Always store tokens securely (not in localStorage for production)
  1. Server-Side Authentication Only
    • Perform authentication on your backend server
    • Never authenticate from browser/mobile client directly
    • Proxy API calls through your backend
  2. Secure Credential Storage 
    # Use environment variables
export TENANT_KEY="cvK_9XDw5g_Y_..."
export TENANT_SECRET="..."
export CLIENT_SECRET="..."

# Or use secret management services
# - AWS Secrets Manager
# - HashiCorp Vault
# - Azure Key Vault
  3. Token Storage
    • Backend: In-memory cache (Redis) with TTL
    • Mobile: Secure keychain/keystore
    • Web: HttpOnly cookies (not localStorage)
  4. Automatic Token Refresh 
    class FinHubClient {
  constructor() {
    this.token = null;
    this.expiresAt = null;
  }
  
  async ensureAuthenticated() {
    const now = new Date();
    const expiryBuffer = 5 * 60 * 1000; // 5 minutes
    
    if (!this.token || now >= (this.expiresAt - expiryBuffer)) {
      await this.authenticate();
    }
  }
  
  async request(url, options = {}) {
    await this.ensureAuthenticated();
    
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${this.token}`,
        'X-Tenant-ID': 'tenant_cloudvault'
      }
    });
  }
}
  5. Rate Limiting
    • Implement exponential backoff for 429 errors
    • Cache responses where appropriate
    • Batch requests when possible
  6. Credential Rotation
    • Rotate tenant secret quarterly
    • Rotate passwords monthly
    • Monitor for suspicious activity

​
Troubleshooting

​
Common Issues

Causes:
  • Incorrect username or password
  • User account disabled
  • User does not have admin privileges
Solution:
  • Verify credentials in Admin Portal
  • Ensure user has ADMIN role
  • Check if account is active
Causes:
  • Invalid tenant key or secret
  • IP address not whitelisted
  • Tenant account suspended
Solution:
  • Regenerate tenant keys in Admin Portal
  • Check IP whitelist settings
  • Contact support if account is suspended
Causes:
  • Token used after expiresAt time
  • Server time drift
Solution:
  • Implement automatic refresh before expiry
  • Sync server time with NTP
  • Re-authenticate if refresh fails
Causes:
  • Session manually invalidated
  • Multiple concurrent sessions
  • Session timeout
Solution:
  • Create new session
  • Implement single session per user if required
  • Check session management policies

Admin Session Management

Complete session management API

User Session Management

Customer authentication flows

Security Best Practices

Comprehensive security guide

API Reference

Browse all API endpoints

​
Changelog

VersionDateChanges
v2.12026-01-13Initial release