URL: /baas/api/integration/flows/individual-customer/session-management

---
title: 'Phase 2: Session Management'
description: '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 |

---

## Create Session (Login)

<Tabs>
  <Tab title="Request">
    **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"
    }
    ```
  </Tab>
  <Tab title="Success Response">
    **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"
        }
      }
    }
    ```
  </Tab>
  <Tab title="Error Responses">
    **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"
      }
    }
    ```
  </Tab>
</Tabs>

---

## 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...
```

<Warning>
  **Token Expiry:** Tokens expire after 1 hour. Use the refresh token to obtain a new access token before expiry.
</Warning>

---

## Delete Session (Logout)

<Tabs>
  <Tab title="Request">
    **Endpoint:** `DELETE /api/v2.1/customer/individual/{customerId}/users/{userId}/sessions/{sessionId}`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    User-Agent: Mozilla/5.0...
    ```
  </Tab>
  <Tab title="Response">
    **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"
      }
    }
    ```
  </Tab>
</Tabs>

---

## 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.

<Card title="Phase 3: Verification" icon="arrow-right" href="/baas/api/integration/flows/individual-customer/verification">
  Submit identity documents for KYC verification
</Card>