Create Session

curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/admin/organization/{organizationId}/users/{userId}/sessions \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --header 'X-Forwarded-For: <x-forwarded-for>' \
  --header 'X-Forwarded-From: <x-forwarded-from>' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --header 'deviceId: <deviceid>' \
  --header 'platform: <platform>' \
  --data '
{
  "username": "admin@finsei.com",
  "password": "Admin@97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "tenantKey": "z6B8H1XAeYSxZbuIlAT1NIRh6Aga",
  "tenantSecret": "zb9anCFp2f2UJNWlGhtB8brsgAca"
}
'

{
  "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"
  }
}

POST

api

v2.1

admin

organization

{organizationId}

users

{userId}

sessions

Create Session

curl --request POST \
  --url https://sandbox.finhub.cloud/api/v2.1/admin/organization/{organizationId}/users/{userId}/sessions \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --header 'X-Forwarded-For: <x-forwarded-for>' \
  --header 'X-Forwarded-From: <x-forwarded-from>' \
  --header 'X-Tenant-ID: <x-tenant-id>' \
  --header 'deviceId: <deviceid>' \
  --header 'platform: <platform>' \
  --data '
{
  "username": "admin@finsei.com",
  "password": "Admin@97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "tenantKey": "z6B8H1XAeYSxZbuIlAT1NIRh6Aga",
  "tenantSecret": "zb9anCFp2f2UJNWlGhtB8brsgAca"
}
'

{
  "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., 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd)

Content-Type

string

required

Must be application/json

string

Response format (default: application/json)

Request Body

username

string

required

Admin username or email addressExample: petr.dvorak@cloudvault.io

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 "Accept: application/json, text/plain, */*" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "username": "petr.dvorak@cloudvault.io",
    "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

Field	Type	Description
`sessionId`	string	Unique session identifier (UUID)
`userId`	string	User ID for this session
`token`	string	JWT access token for API authentication
`refreshToken`	string	Token for refreshing the session
`expiresAt`	string	ISO 8601 timestamp when token expires
`success`	boolean	Always `true` for successful responses
`message`	string	Human-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 "Accept: application/json, text/plain, */*" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809"

The token must be included in the Authorization header with the Bearer prefix.

Security Best Practices

Critical Security Requirements:

Never expose tenantSecret or clientSecret in client-side code
Always use HTTPS in production
Store credentials securely (use environment variables or secret management)
Rotate secrets regularly (every 90 days recommended)
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

Version	Date	Changes
v2.1	2026-01-13	Initial release

Headers

User-Agent

string

required

Browser user agent

Example:

"Mozilla/5.0"

X-Forwarded-For

string

required

Client/application Ip address

Example:

"192.168.0.1"

X-Forwarded-From

string

required

Client/application identifier for request source tracking

Example:

"playground"

X-Tenant-ID

string

required

Tenant identifier

Example:

"97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platform

Example:

"web"

deviceId

string

required

Device identifier

Example:

"e2e-test-device"

Path Parameters

organizationId

string

required

Organization identifier (UUID)

Example:

"b4c3d4e7-f8a9-0123-b4c5-d6e7f8a9012b"

userId

string

required

User identifier (UUID)

Example:

"87b3af37-4ac1-402b-a0ea-53cfdc695e02"

Body

application/json

username

string

required

Example:

"admin@finsei.com"

password

string

required

Example:

"Admin@97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

tenantKey

string

required

Tenant-level authentication key

Example:

"z6B8H1XAeYSxZbuIlAT1NIRh6Aga"

tenantSecret

string

required

Tenant-level authentication secret

Example:

"zb9anCFp2f2UJNWlGhtB8brsgAca"

Response

Session created successfully

Standard API response wrapper used by all endpoints

code

integer

HTTP status code

Example:

200

data

object

Response from session creation endpoints

Show child attributes

message

string

Human-readable status message

Example:

"Success"

Administration User Management API

⌘I

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Admin Session Management API

Admin Session Management API

Create Admin Session

Endpoint

Path Parameters

Headers

Request Body

Code Examples

Response

Response Fields

Success Response Data

Token Details

Using the Session Token

Security Best Practices

Credential Storage

Token Refresh

Common Errors

Missing Tenant Credentials

Invalid Credentials

Organization/User Not Found

Customer Session Login

Admin Roles

Audit Logs

Common Types

Changelog

Headers

Path Parameters

Body

Response

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Admin Session Management API

​Create Admin Session

​Endpoint

​Path Parameters

​Headers

​Request Body

​Code Examples

​Response

​Response Fields

​Success Response Data

​Token Details

​Using the Session Token

​Security Best Practices

​Credential Storage

​Token Refresh

​Common Errors

​Missing Tenant Credentials

​Invalid Credentials

​Organization/User Not Found

​Related Endpoints

Customer Session Login

Admin Roles

Audit Logs

Common Types

​Changelog

Headers

Path Parameters

Body

Response

Admin Session Management API

Create Admin Session

Endpoint

Path Parameters

Headers

Request Body

Code Examples

Response

Response Fields

Success Response Data

Token Details

Using the Session Token

Security Best Practices

Credential Storage

Token Refresh

Common Errors

Missing Tenant Credentials

Invalid Credentials

Organization/User Not Found

Related Endpoints

Changelog