Internal APIs

The Internal APIs provide server-to-server communication between the Tournament System and Game Platform. These APIs enable tournament configuration retrieval, player list access, status monitoring, and tournament creation for hop-on/off formats.

Authentication

All internal APIs require authentication via internal API keys in the Authorization header:

GET /internal/tournaments/12345/config
Authorization: Bearer {internal-api-key}
Content-Type: application/json

Internal API Keys are high-privilege keys intended only for secure server-to-server communication. Never expose these keys in client-side code or public repositories.

Tournament Configuration APIs

Get Tournament Configuration

Retrieve complete tournament configuration for game room setup:

GET /internal/tournaments/{tournamentId}/config
Authorization: Bearer {internal-api-key}

Response:

{
  "tournamentId": "12345",
  "name": "Daily Championship",
  "gameSlug": "crash-classic",
  "status": "active",
  "maxPlayers": 100,
  "currentPlayers": 87,
  "minPlayers": 5,
  "startTime": "2024-01-15T20:00:00Z",
  "gameConfig": {
    "maxRounds": 10,
    "roundDuration": 300,
    "eliminationRate": 0.5,
    "gameRules": {
      "crashMultiplier": {
        "min": 1.0,
        "max": 100.0
      },
      "autoPlayEnabled": true,
      "maxBetAmount": 1000.0
    }
  },
  "prizePool": {
    "type": "percentage",
    "totalAmount": 870.00,
    "distribution": [50, 30, 20],
    "guaranteedPrize": 500.00
  },
  "roomId": "room_abc123",
  "roomUrl": "https://game.platform.com/room/abc123",
  "rebuyConfig": {
    "enabled": true,
    "fee": 10.00,
    "maxEntriesPerPlayer": 3,
    "deadline": "2024-01-15T20:30:00Z"
  },
  "operatorConfig": {
    "operatorId": "op_1234567890abcdef",
    "branding": {
      "primaryColor": "#8B5CF6",
      "logoUrl": "https://operator.com/logo.png"
    },
    "features": {
      "allowLateRegistration": false,
      "showTimer": true,
      "showLeaderboard": true
    }
  }
}

Get Tournament Status

Monitor real-time tournament status and progress:

GET /internal/tournaments/{tournamentId}/status  
Authorization: Bearer {internal-api-key}

Response:

{
  "tournamentId": "12345",
  "status": "in_progress",
  "currentPlayers": 87,
  "maxPlayers": 100,
  "startTime": "2024-01-15T20:00:00Z",
  "actualStartTime": "2024-01-15T20:02:15Z",
  "estimatedEndTime": "2024-01-15T21:15:00Z",
  "currentRound": 3,
  "totalRounds": 5,
  "eliminations": 23,
  "gameRoom": {
    "roomId": "room_abc123",
    "activeConnections": 87,
    "lastActivity": "2024-01-15T20:25:30Z"
  },
  "prizePool": {
    "totalAmount": 870.00,
    "locked": true
  },
  "timing": {
    "roundStartTime": "2024-01-15T20:20:00Z",
    "roundEndTime": "2024-01-15T20:25:00Z",
    "nextRoundStart": "2024-01-15T20:30:00Z"
  }
}

Tournament Status Values

Status	Description	Game Platform Actions
`scheduled`	Tournament created, waiting for start	Prepare game room, wait for start signal
`open`	Registration open, not started	Accept player connections, show lobby
`in_progress`	Tournament actively running	Manage gameplay, process player actions
`completed`	Tournament finished	Calculate final results, cleanup room
`cancelled`	Tournament cancelled	Cleanup room, handle player disconnections

Player Management APIs

Get Tournament Players

Retrieve list of registered players for tournament setup:

GET /internal/tournaments/{tournamentId}/players
Authorization: Bearer {internal-api-key}

Query Parameters:

status - Filter by player status (active, registered, eliminated)
includeEliminated - Include eliminated players (default: false)
limit - Results per page (default: 100, max: 500)

Response:

{
  "tournamentId": "12345",
  "players": [
    {
      "playerId": "tp_player_456",
      "internalPlayerId": "session_789", 
      "displayName": "PlayerName",
      "status": "active",
      "entryCount": 2,
      "totalPaid": 20.00,
      "registeredAt": "2024-01-15T19:30:00Z",
      "gameStats": {
        "currentPosition": 15,
        "points": 1250,
        "gamesPlayed": 8,
        "averageScore": 156.25,
        "currentRound": 3
      },
      "connectionInfo": {
        "lastActiveAt": "2024-01-15T20:25:30Z",
        "connectionStatus": "connected",
        "ipAddress": "192.168.1.100"
      },
      "permissions": ["play", "rebuy", "chat"],
      "metadata": {
        "vipLevel": "gold",
        "preferredLanguage": "en"
      }
    }
  ],
  "pagination": {
    "total": 87,
    "limit": 100,
    "offset": 0
  }
}

Tournament Creation APIs (Hop-on/Off Only)

Create Tournament

Create on-demand tournament for hop-on/off format:

POST /internal/tournaments
Authorization: Bearer {internal-api-key}
Content-Type: application/json

{
  "name": "Crash #1642089600",
  "type": "hop_on_off",
  "gameSlug": "crash-classic", 
  "minPlayers": 5,
  "maxPlayers": 50,
  "startCondition": "min_players_reached",
  "entryFee": 5.00,
  "prizePool": {
    "type": "percentage",
    "distribution": [60, 25, 15]
  },
  "rebuyEnabled": true,
  "rebuyFee": 5.00,
  "maxEntriesPerPlayer": 2,
  "gameConfig": {
    "maxRounds": 5,
    "roundDuration": 180,
    "eliminationRate": 0.6
  }
}

Response:

{
  "tournamentId": "12346",
  "status": "scheduled",
  "name": "Crash #1642089600",
  "type": "hop_on_off", 
  "minPlayers": 5,
  "currentPlayers": 0,
  "startCondition": "min_players_reached",
  "created": "2024-01-15T20:30:00Z",
  "gameConfig": {
    "maxRounds": 5,
    "roundDuration": 180,
    "eliminationRate": 0.6
  }
}

Remove Player (Hop-on/Off Only)

Remove player from tournament before start with refund:

DELETE /internal/tournaments/{tournamentId}/players/{playerId}
Authorization: Bearer {internal-api-key}
Content-Type: application/json

{
  "reason": "left_before_start",
  "processRefund": true
}

Response:

{
  "playerId": "tp_player_456",
  "tournamentId": "12346",
  "removed": true,
  "refundProcessed": true,
  "refundAmount": 10.00,
  "reason": "left_before_start",
  "remainingPlayers": 3,
  "tournamentStatus": "scheduled"
}

Integration Examples

Tournament Configuration Flow

// Retrieve tournament configuration for game room setup
const setupTournamentRoom = async (tournamentId) => {
  try {
    // Get tournament configuration
    const configResponse = await fetch(`/internal/tournaments/${tournamentId}/config`, {
      headers: {
        'Authorization': 'Bearer internal-api-key',
        'Content-Type': 'application/json'
      }
    });
    
    if (!configResponse.ok) {
      throw new Error(`Config fetch failed: ${configResponse.status}`);
    }
    
    const config = await configResponse.json();
    
    // Get registered players
    const playersResponse = await fetch(`/internal/tournaments/${tournamentId}/players`, {
      headers: {
        'Authorization': 'Bearer internal-api-key'
      }
    });
    
    const playersData = await playersResponse.json();
    
    // Initialize game room with configuration
    const gameRoom = await initializeGameRoom({
      tournamentId: config.tournamentId,
      gameConfig: config.gameConfig,
      players: playersData.players,
      prizePool: config.prizePool,
      rebuyConfig: config.rebuyConfig
    });
    
    console.log(`Tournament room initialized: ${gameRoom.roomId}`);
    return gameRoom;
    
  } catch (error) {
    console.error('Tournament setup failed:', error);
    throw error;
  }
};

Hop-on/Off Tournament Creation

// Create new tournament when first player joins lobby
const createHopOnOffTournament = async (gameSlug, playerCount = 5) => {
  const timestamp = Math.floor(Date.now() / 1000);
  
  try {
    const response = await fetch('/internal/tournaments', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer internal-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `${gameSlug} #${timestamp}`,
        type: 'hop_on_off',
        gameSlug: gameSlug,
        minPlayers: playerCount,
        maxPlayers: playerCount * 10,
        startCondition: 'min_players_reached',
        entryFee: 5.00,
        prizePool: {
          type: 'percentage',
          distribution: [60, 25, 15]
        },
        rebuyEnabled: true,
        rebuyFee: 5.00,
        maxEntriesPerPlayer: 3
      })
    });
    
    const tournament = await response.json();
    
    console.log(`Created hop-on/off tournament: ${tournament.tournamentId}`);
    return tournament;
    
  } catch (error) {
    console.error('Tournament creation failed:', error);
    throw error;
  }
};

Tournament Status Monitoring

// Monitor tournament status with polling
class TournamentMonitor {
  constructor(tournamentId, intervalMs = 5000) {
    this.tournamentId = tournamentId;
    this.intervalMs = intervalMs;
    this.monitoring = false;
  }
  
  async startMonitoring() {
    this.monitoring = true;
    
    while (this.monitoring) {
      try {
        const response = await fetch(`/internal/tournaments/${this.tournamentId}/status`, {
          headers: {
            'Authorization': 'Bearer internal-api-key'
          }
        });
        
        const status = await response.json();
        
        // Handle status changes
        this.handleStatusChange(status);
        
        // Stop monitoring if tournament completed
        if (status.status === 'completed' || status.status === 'cancelled') {
          this.stopMonitoring();
          break;
        }
        
        // Wait before next poll
        await new Promise(resolve => setTimeout(resolve, this.intervalMs));
        
      } catch (error) {
        console.error('Status monitoring error:', error);
        // Continue monitoring despite errors
      }
    }
  }
  
  stopMonitoring() {
    this.monitoring = false;
    console.log(`Stopped monitoring tournament ${this.tournamentId}`);
  }
  
  handleStatusChange(status) {
    console.log(`Tournament ${this.tournamentId} status: ${status.status}`);
    console.log(`Players: ${status.currentPlayers}/${status.maxPlayers}`);
    
    if (status.currentRound) {
      console.log(`Round: ${status.currentRound}/${status.totalRounds}`);
    }
  }
}

// Usage
const monitor = new TournamentMonitor('12345');
monitor.startMonitoring();

Error Handling

Common Error Responses

Tournament Not Found

{
  "error": "tournament_not_found",
  "message": "Tournament with ID 12345 not found",
  "tournamentId": "12345"
}

Invalid Internal API Key

{
  "error": "unauthorized",
  "message": "Invalid internal API key",
  "code": "INVALID_INTERNAL_KEY"
}

Tournament Not Ready

{
  "error": "tournament_not_ready", 
  "message": "Tournament configuration not available - tournament may not be active",
  "tournamentStatus": "scheduled"
}

Error Handling Best Practices

Retry Logic

Implement exponential backoff for failed requests with circuit breaker patterns

Status Validation

Always validate tournament status before attempting operations

Graceful Degradation

Handle API failures gracefully without breaking game functionality

Monitoring

Monitor internal API response times and error rates

Rate Limits

Internal APIs have higher rate limits than external APIs:

Operation Type	Limit	Window
Tournament Configuration	1000 requests	per minute
Player Data Retrieval	2000 requests	per minute
Status Monitoring	1000 requests	per minute
Tournament Creation	100 requests	per minute

Internal APIs

Real-time Integration

Internal APIs

Internal APIs

Authentication

Tournament Configuration APIs

Get Tournament Configuration

Get Tournament Status

Tournament Status Values

Player Management APIs

Get Tournament Players

Tournament Creation APIs (Hop-on/Off Only)

Create Tournament

Remove Player (Hop-on/Off Only)

Integration Examples

Tournament Configuration Flow

Hop-on/Off Tournament Creation

Tournament Status Monitoring

Error Handling

Common Error Responses

Tournament Not Found

Invalid Internal API Key

Tournament Not Ready

Error Handling Best Practices

Retry Logic

Status Validation

Graceful Degradation

Monitoring

Rate Limits

Next Steps

JWT Authentication

Event Reporting

​Internal APIs

​Authentication

​Tournament Configuration APIs

​Get Tournament Configuration

​Get Tournament Status

​Tournament Status Values

​Player Management APIs

​Get Tournament Players

​Tournament Creation APIs (Hop-on/Off Only)

​Create Tournament

​Remove Player (Hop-on/Off Only)

​Integration Examples

​Tournament Configuration Flow

​Hop-on/Off Tournament Creation

​Tournament Status Monitoring

​Error Handling

​Common Error Responses

​Tournament Not Found

​Invalid Internal API Key

​Tournament Not Ready

​Error Handling Best Practices

Retry Logic

Status Validation

Graceful Degradation

Monitoring

​Rate Limits

​Next Steps

JWT Authentication

Event Reporting

Internal APIs

Authentication

Tournament Configuration APIs

Get Tournament Configuration

Get Tournament Status

Tournament Status Values

Player Management APIs

Get Tournament Players

Tournament Creation APIs (Hop-on/Off Only)

Create Tournament

Remove Player (Hop-on/Off Only)

Integration Examples

Tournament Configuration Flow

Hop-on/Off Tournament Creation

Tournament Status Monitoring

Error Handling

Common Error Responses

Tournament Not Found

Invalid Internal API Key

Tournament Not Ready

Error Handling Best Practices

Rate Limits

Next Steps