Skip to main content
POST
https://sandbox.finhub.cloud
/
api
/
v2.1
/
admin
/
organization
/
{organizationId}
/
users
/
{userId}
/
sessions
Admin Session Management API
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.eyJpc3MiOiJiZmYiLCJhdWQiOiJiZmYtY2xpZW50cyIsInN1YiI6ImUyZjNhNGI1LWM2ZDctNDhlOS0wZjFhLTJiM2M0ZDVlNmY3YSIsImV4cCI6MTc2ODI0OTMwOCwiaWF0IjoxNzY4MjQ1NzA4LCJ0ZW5hbnRJZCI6ImQxZTJmM2E0LWI1YzYtNDdkOC05ZTBmLTFhMmIzYzRkNWU2ZiIsImN1c3RvbWVySWQiOiJmM2E0YjVjNi1kN2U4LTQ5ZjAtMWEyYi0zYzRkNWU2ZjdhOGIiLCJ1c2VySWQiOiJlMmYzYTRiNS1jNmQ3LTQ4ZTktMGYxYS0yYjNjNGQ1ZTZmN2EiLCJ1c2VyVHlwZSI6IkFETUlOIiwicm9sZXMiOlsiQURNSU4iXSwianRpIjoiMGNiZjU2NTAtOWQzZS00NTE3LWE5NDMtNWM0NTY2MTEzN2Y1In0.ErBD1mBCkoqdpaxEoDAHxu4V3ZvqJy-OmNi5gRF7t98",
    "refreshToken": "3c68d5a6-d567-4ec7-88df-c8df22ff6151-e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a-cvK_9XDw",
    "expiresAt": "2026-01-13T22:21:48.9745432",
    "success": true,
    "message": "Session created successfully"
  }
}

​
Admin Session Management API

APIs for managing administrative sessions and multi-tenant authentication.
Base URL: https://sandbox.finhub.cloud

​
Create Admin Session

Creates an authenticated session for an administrative user within an organization context.

​
Endpoint

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

​
Path Parameters

​
organizationId
string
required
Organization UUID identifierExample: f3a4b5c6-d7e8-49f0-1a2b-3c4d5e6f7a8b
​
userId
string
required
User UUID identifier within the organizationExample: e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a

​
Headers

​
X-Tenant-ID
string
required
Tenant identifier (e.g., tenant_cloudvault)
​
Content-Type
string
required
Must be application/json
​
Accept
string
Response format (default: application/json)

​
Request Body

​
username
string
required
Admin username or email addressExample: [email protected]
​
password
string
required
Admin password (will be redacted in logs)
​
tenantKey
string
required
Tenant-level authentication keyExample: cvK_9XDw5g_Y_8aUtRQgPyX4aTBb
This is required for multi-tenant authentication
​
tenantSecret
string
required
Tenant-level authentication secret (sensitive)

​
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" \
  -H "Accept: 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.eyJpc3MiOiJiZmYiLCJhdWQiOiJiZmYtY2xpZW50cyIsInN1YiI6ImUyZjNhNGI1LWM2ZDctNDhlOS0wZjFhLTJiM2M0ZDVlNmY3YSIsImV4cCI6MTc2ODI0OTMwOCwiaWF0IjoxNzY4MjQ1NzA4LCJ0ZW5hbnRJZCI6ImQxZTJmM2E0LWI1YzYtNDdkOC05ZTBmLTFhMmIzYzRkNWU2ZiIsImN1c3RvbWVySWQiOiJmM2E0YjVjNi1kN2U4LTQ5ZjAtMWEyYi0zYzRkNWU2ZjdhOGIiLCJ1c2VySWQiOiJlMmYzYTRiNS1jNmQ3LTQ4ZTktMGYxYS0yYjNjNGQ1ZTZmN2EiLCJ1c2VyVHlwZSI6IkFETUlOIiwicm9sZXMiOlsiQURNSU4iXSwianRpIjoiMGNiZjU2NTAtOWQzZS00NTE3LWE5NDMtNWM0NTY2MTEzN2Y1In0.ErBD1mBCkoqdpaxEoDAHxu4V3ZvqJy-OmNi5gRF7t98",
    "refreshToken": "3c68d5a6-d567-4ec7-88df-c8df22ff6151-e2f3a4b5-c6d7-48e9-0f1a-2b3c4d5e6f7a-cvK_9XDw",
    "expiresAt": "2026-01-13T22:21:48.9745432",
    "success": true,
    "message": "Session created successfully"
  }
}

​
Response Fields

​
Success Response Data

FieldTypeDescription
sessionIdstringUnique session identifier (UUID)
userIdstringUser ID for this session
tokenstringJWT access token for API authentication
refreshTokenstringToken for refreshing the session
expiresAtstringISO 8601 timestamp when token expires
successbooleanAlways true for successful responses
messagestringHuman-readable success message

​
Token Details

The JWT token contains:
  • Issuer: bff
  • Audience: bff-clients
  • Subject: User ID
  • Expiry: 1 hour from issue time
  • Custom Claims:
    • tenantId: Tenant identifier
    • customerId: Organization/customer ID
    • userId: User identifier
    • userType: "ADMIN"
    • roles: Array of user roles (e.g., ["ADMIN"])

​
Using the Session Token

After successful login, use the token in all subsequent API requests: 
curl -X GET "https://sandbox.finhub.cloud/api/v2.1/some-endpoint" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-ID: tenant_cloudvault"
The token must be included in the Authorization header with the Bearer prefix.

​
Security Best Practices

Critical Security Requirements:
  1. Never expose tenantSecret or clientSecret in client-side code
  2. Always use HTTPS in production
  3. Store credentials securely (use environment variables or secret management)
  4. Rotate secrets regularly (every 90 days recommended)
  5. Monitor failed login attempts for security threats

​
Credential Storage

// Never hardcode credentials
const tenantSecret = 'my_secret_123'; // Don't do this

// Use environment variables instead
const tenantSecret = process.env.TENANT_SECRET;

// Or use secret management service
const tenantSecret = await secretManager.getSecret('tenant_secret');

​
Token Refresh

When the token expires (check expiresAt timestamp), use the refreshToken to obtain a new access token without requiring the user to re-authenticate.
Token refresh endpoint documentation coming soon. Currently, you should re-authenticate when the token expires.

​
Common Errors

​
Missing Tenant Credentials

Problem: Request fails with 400 Bad Request Cause: Missing tenantKey or tenantSecret in request body Solution: Ensure all required authentication fields are included: 
{
  "username": "...",
  "password": "...",
  "tenantKey": "...",
  "tenantSecret": "..."
}

​
Invalid Credentials

Problem: 401 Unauthorized response Cause: Incorrect username, password, or tenant credentials Solution: Verify:
  • Username/email is correct
  • Password is correct
  • Tenant keys are valid for the specified tenant ID
  • Organization ID and User ID match the authenticated user

​
Organization/User Not Found

Problem: 404 Not Found Cause: Invalid organization ID or user ID in URL path Solution: Verify the UUIDs are correct and the user belongs to the specified organization

Customer Session Login

Session creation for individual customers

Admin Roles

View and manage administrative roles

Audit Logs

Track admin session activity and changes

Common Types

Standard response structures and data types

​
Changelog

VersionDateChanges
v2.12026-01-13Initial release