🎮 Funday Gaming Platform - API Documentation

Complete API reference for the Funday gaming platform backend.

Authentication

Platform Token Provider

GET /api/auth/nakama-token

Returns authenticated Nakama session token for current user.

Response:

{
  "success": true,
  "token": "eyJ...",
  "refresh_token": "eyJ...",
  "user_id": "user-123",
  "username": "BraveWolf42",
  "expires_at": 1760239800000
}

Usage in Game Plugins:

const response = await fetch("/api/auth/nakama-token")
const { token } = await response.json()
// Use token for Nakama operations

Games API

List All Games

GET /api/games

Returns array of available games from plugin manifests.

Response:

{
  "success": true,
  "games": [
    {
      "id": "nitro-racers",
      "title": "Nitro Racers",
      "description": "Professional racing game with multiplayer",
      "thumbnail": "/images/games/nitro-racers.jpg",
      "rating": { "average": 4.3, "count": 124 },
      "playerCount": { "current": 2200, "max": 8, "min": 1 },
      "status": "available",
      "gameType": "multiplayer",
      "integrationType": "iframe-themeable",
      "playUrl": "/game-plugins/nitro-racers/index-v2.html"
    }
  ]
}

Get Game Details

GET /api/games/{id}

Returns detailed information for specific game.

Response: Same as list item with additional metadata.

Launch Game

POST /api/games/{id}/launch

Launches game session and returns play URL.

Response:

{
  "success": true,
  "session": {
    "id": "session-123",
    "gameId": "nitro-racers",
    "playUrl": "/game-plugins/nitro-racers/index-v2.html"
  }
}

Leaderboards

Submit Score

POST /api/leaderboards/submit

Submits score to Nakama leaderboard.

Request:

{
  "leaderboardId": "nitro-racers-best-lap",
  "score": 15000,
  "subscore": 45000,
  "metadata": {
    "lapTime": 45.0,
    "lapNumber": 3
  }
}

Response:

{
  "success": true,
  "record": {
    "leaderboard_id": "nitro-racers-best-lap",
    "owner_id": "user-123",
    "score": 15000,
    "rank": 42
  }
}

User Management

Update Username

PUT /api/user/username

Updates user’s display name in Nakama.

Request:

{
  "username": "NewAwesomeName"
}

Response:

{
  "success": true,
  "username": "NewAwesomeName"
}

Rate Limits: 3 changes per hour per user.

Error Handling

All endpoints return standard error format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Common Status Codes:

200: Success
400: Bad Request (validation error)
401: Unauthorized (no session)
429: Rate Limited
500: Internal Server Error

Integration Examples

Game Plugin Auth

// In game plugin iframe
class GameAuth {
  async authenticate() {
    const response = await fetch("/api/auth/nakama-token")
    const { token, user_id } = await response.json()
    // Use token for Nakama operations
  }
}

Leaderboard Integration

// Submit score after game completion
await fetch("/api/leaderboards/submit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    leaderboardId: "game-leaderboard-id",
    score: playerScore,
  }),
})

Security Notes

All tokens are short-lived and refreshed automatically
CORS configured for platform origins only
Rate limiting prevents abuse
Input validation on all endpoints
No sensitive data in client-side code