> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

***

## 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 theme={null}
    {
      "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 theme={null}
    {
      "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 theme={null}
    {
      "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 theme={null}
    {
      "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 theme={null}
    {
      "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 theme={null}
{
  "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 theme={null}
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 theme={null}
    Authorization: Bearer {jwt-token}
    User-Agent: Mozilla/5.0...
    ```
  </Tab>

  <Tab title="Response">
    **Status:** `200 OK`

    ```json theme={null}
    {
      "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>