The Sessions API allows you to track player activity and engagement by managing session lifecycle. All session endpoints require authentication.

​
Base URL

All session endpoints are prefixed with /api/game/session/.

​
Authentication

All session endpoints require a valid JWT token in the Authorization header: 
Authorization: Bearer <your-jwt-token>

​
Start Session

Begin tracking a new player session. Endpoint: POST /api/game/session/start Headers: 
Authorization: Bearer <your-jwt-token>
Response: 
{
  "statusCode": 200,
  "data": {
    "sessionId": "session-uuid",
    "startTime": "2024-01-01T12:00:00Z",
    "playerId": "player-id"
  }
}

​
Heartbeat

Keep the session alive and update the last activity timestamp. Endpoint: POST /api/game/session/heartbeat Headers: 
Authorization: Bearer <your-jwt-token>
Response: 
{
  "statusCode": 200,
  "data": {
    "sessionId": "session-uuid",
    "lastActivity": "2024-01-01T12:30:00Z",
    "playerId": "player-id"
  }
}

​
End Session

Stop tracking the current session. Endpoint: POST /api/game/session/stop Headers: 
Authorization: Bearer <your-jwt-token>
Response: 
{
  "statusCode": 200,
  "data": {
    "sessionId": "session-uuid",
    "startTime": "2024-01-01T12:00:00Z",
    "endTime": "2024-01-01T13:00:00Z",
    "duration": 3600,
    "playerId": "player-id"
  }
}

​
Session Management Best Practices

  1. Start Session: Call when the player begins playing your game
  2. Heartbeat: Call periodically (every 5-10 minutes) to keep the session active
  3. End Session: Call when the player stops playing or closes the game

​
Error Responses

​
Unauthorized

{
  "statusCode": 401,
  "error": {
    "message": "Unauthorized"
  }
}

​
Session Already Active

{
  "statusCode": 400,
  "error": {
    "message": "Session already active"
  }
}

​
No Active Session

{
  "statusCode": 400,
  "error": {
    "message": "No active session found"
  }
}