Phase 2: Session Management Session management handles user authentication and maintains user state across API calls using JWT tokens.
Overview Aspect Details Token Type JWT (JSON Web Token) Algorithm HS256 Expiry 1 hour (3600 seconds) Refresh Via refresh token
Create Session (Login) Request
Success Response
Error Responses
Endpoint: POST /api/v2.1/customer/individual/{customerId}/users/{userId}/sessionsPath Parameters:
customerId: Customer UUID from registrationuserId: User UUID from registration Request Body: { "username" : "[email protected] " , "password" : "SecurePass123!@#" , "tenantKey" : "fh_api_finsei_ltd_7f957f77" , "tenantSecret" : "your-tenant-secret-key" }
Status: 200 OK{ "code" : 200 , "message" : "Session created successfully" , "data" : { "success" : true , "sessionId" : "sess-770e8400-e29b-41d4-a716-446655440020" , "token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." , "tokenType" : "Bearer" , "expiresIn" : 3600 , "userId" : "user-660e8400-e29b-41d4-a716-446655440011" , "customerId" : "cust-550e8400-e29b-41d4-a716-446655440010" , "roles" : [ "USER" ], "tenantId" : "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" , "sessionMetadata" : { "clientIp" : "192.168.1.100" , "clientPlatform" : "Windows" , "userAgent" : "Mozilla/5.0..." , "createdAt" : "2026-01-13T11:00:00.000Z" } } }
401 - Invalid Credentials: { "code" : 401 , "message" : "Authentication failed" , "data" : { "success" : false , "errorType" : "AUTHENTICATION" , "message" : "Invalid username or password" , "attempts" : 3 , "maxAttempts" : 5 , "lockoutTime" : null } }
401 - Account Locked: { "code" : 401 , "message" : "Account locked" , "data" : { "success" : false , "errorType" : "AUTHENTICATION" , "message" : "Account locked due to multiple failed login attempts" , "attempts" : 5 , "maxAttempts" : 5 , "lockoutTime" : "2026-01-13T11:30:00.000Z" , "lockoutDuration" : "30 minutes" } }
404 - User Not Found: { "code" : 404 , "message" : "User not found" , "data" : { "success" : false , "errorType" : "NOT_FOUND" , "message" : "User with username '[email protected] ' not found in tenant" } }
JWT Token Structure Decoded Token { "header" : { "alg" : "HS256" , "typ" : "JWT" }, "payload" : { "sub" : "user-660e8400-e29b-41d4-a716-446655440011" , "customerId" : "cust-550e8400-e29b-41d4-a716-446655440010" , "tenantId" : "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" , "roles" : [ "USER" ], "email" : "[email protected] " , "sessionId" : "sess-770e8400-e29b-41d4-a716-446655440020" , "iat" : 1705148400 , "exp" : 1705152000 , "iss" : "muse-proxy-bff" , "aud" : "finhub-services" } }
Token Claims Claim Description subUser ID (subject) customerIdCustomer ID tenantIdTenant UUID rolesUser roles array sessionIdSession identifier iatIssued at timestamp expExpiration timestamp issIssuer audAudience
Using the JWT Token Include the token in all subsequent API calls:
Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Token Expiry: Tokens expire after 1 hour. Use the refresh token to obtain a new access token before expiry.
Delete Session (Logout) Endpoint: DELETE /api/v2.1/customer/individual/{customerId}/users/{userId}/sessions/{sessionId}Headers: Authorization : Bearer {jwt-token} X-Forwarded-For : 192.168.1.100 User-Agent : Mozilla/5.0...
Status: 200 OK{ "code" : 200 , "message" : "Session deleted successfully" , "data" : { "success" : true , "sessionId" : "sess-770e8400-e29b-41d4-a716-446655440020" , "deletedAt" : "2026-01-13T12:00:00.000Z" } }
Session Security Lockout Policy Metric Value Max Failed Attempts 5 Lockout Duration 30 minutes Lockout Reset After successful login
Client IP address
User agent string
Platform information
Creation timestamp
Last activity timestamp
Next Step After creating a session, proceed to Phase 3: Verification to complete KYC verification.
Phase 3: Verification Submit identity documents for KYC verification
