Phase 2: Session Management

Authentication, JWT tokens, and session lifecycle

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

Endpoint: POST /api/v2.1/customer/individual/{customerId}/users/{userId}/sessions

Path Parameters:

customerId: Customer UUID from registration
userId: User UUID from registration

Request Body:

json

{
  "username": "john.doe@example.com",
  "password": "SecurePass123!@#",
  "tenantKey": "fh_api_finsei_ltd_7f957f77",
  "tenantSecret": "your-tenant-secret-key"
}

Status: 200 OK

json

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

json

{
  "code": 401,
  "message": "Authentication failed",
  "data": {
    "success": false,
    "errorType": "AUTHENTICATION",
    "message": "Invalid username or password",
    "attempts": 3,
    "maxAttempts": 5,
    "lockoutTime": null
  }
}

401 - Account Locked:

json

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

json

{
  "code": 404,
  "message": "User not found",
  "data": {
    "success": false,
    "errorType": "NOT_FOUND",
    "message": "User with username 'john.doe@example.com' not found in tenant"
  }
}

JWT Token Structure

Decoded Token

json

{
  "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": "john.doe@example.com",
    "sessionId": "sess-770e8400-e29b-41d4-a716-446655440020",
    "iat": 1705148400,
    "exp": 1705152000,
    "iss": "muse-proxy-bff",
    "aud": "finhub-services"
  }
}

Token Claims

Claim	Description
`sub`	User ID (subject)
`customerId`	Customer ID
`tenantId`	Tenant UUID
`roles`	User roles array
`sessionId`	Session identifier
`iat`	Issued at timestamp
`exp`	Expiration timestamp
`iss`	Issuer
`aud`	Audience

Using the JWT Token

Include the token in all subsequent API calls:

http

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Delete Session (Logout)

Endpoint: DELETE /api/v2.1/customer/individual/{customerId}/users/{userId}/sessions/{sessionId}

Headers:

http

Authorization: Bearer {jwt-token}
User-Agent: Mozilla/5.0...

Status: 200 OK

json

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

Session Metadata Captured

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

Phase 2: Session Management

Overview

Create Session (Login)

JWT Token Structure

Decoded Token

Token Claims

Using the JWT Token

Delete Session (Logout)

Session Security

Lockout Policy

Session Metadata Captured

Next Step