Authentication Guide

This guide explains how to implement authentication in your game using Games.fun. We use JWT (JSON Web Tokens) to secure communication between your game client and server.

Setup Steps

1. Get Public Key

First, your game server needs to get the platform's public key for verifying tokens:

// On your game server
const response = await fetch('https://games.fun/api/games/auth/keys');
const { 
    public_key, 
    algorithm,  // 'RS256'
    issuer     // 'games.fun'
} = await response.json();

// Store these for token verification

2. Client Authentication

In your game client, request a JWT when needed:

// Using vanilla SDK
const sdk = new GamesFunSDK({
    gameServerUrl: "your-validation-endpoint"
});

// Request JWT token
const result = await sdk.triggerAction("issueJWT", {});
const jwt = result.params.jwt;

// Use with game server
gameServer.setJWT(jwt);

Using React hooks:

function Game() {
    const { triggerAction } = useGamesFun();
    const [authToken, setAuthToken] = useState(null);

    const authenticate = async () => {
        const result = await triggerAction("issueJWT", {});
        setAuthToken(result.params.jwt);
        gameServer.setJWT(result.params.jwt);
    };
}

3. Token Verification

On your game server, verify tokens before processing authenticated requests:

// Create a verification function
const verifyPlayerToken = async (token) => {
    try {
        const result = await JWTUtils.verifyToken(token, public_key, {
            issuer,
            algorithms: [algorithm]
        });

        if (!result.valid) {
            throw new Error('Invalid token');
        }

        // Check expiration
        if (result.payload.exp && Date.now() >= result.payload.exp * 1000) {
            throw new Error('Token expired');
        }

        return {
            valid: true,
            playerId: result.payload.sub
        };
    } catch (error) {
        return {
            valid: false,
            error: error.message
        };
    }
};

// Use in request handlers
app.post('/api/purchase', async (req, res) => {
    const { jwt } = req.headers;
    const authResult = await verifyPlayerToken(jwt);
    
    if (!authResult.valid) {
        return res.status(401).json({ error: 'Authentication failed' });
    }

    // Process authenticated request...
});

4. WebSocket Authentication

For WebSocket connections:

// Client side
const gameServer = new GameServer('wss://your-game-server');
gameServer.setJWT(authToken);
gameServer.connect(sdk.getConnection().privyId);

// Server side
wss.on('connection', (ws) => {
    let isAuthenticated = false;
    let playerId = null;

    ws.on('message', async (data) => {
        const message = JSON.parse(data);

        // Require auth for protected actions
        if (!isAuthenticated && message.type !== 'register') {
            ws.send(JSON.stringify({
                type: 'error',
                error: 'Authentication required'
            }));
            return;
        }

        // Handle authenticated messages...
    });
});

Error Handling

Client Side

try {
    await gameServer.purchaseItem(itemId, price);
} catch (error) {
    if (error.message.includes('Authentication')) {
        // Token expired - get new one
        const newToken = await getAuthToken();
        gameServer.setJWT(newToken);
        
        // Retry request
        await gameServer.purchaseItem(itemId, price);
    }
}

Server Side

try {
    const authResult = await verifyPlayerToken(jwt);
    if (!authResult.valid) {
        if (authResult.error === 'Token expired') {
            // Ask client to get new token
            return res.status(401).json({
                error: 'Token expired',
                shouldReauth: true
            });
        }
        return res.status(401).json({ error: 'Authentication failed' });
    }
} catch (error) {
    console.error('Auth error:', error);
    return res.status(500).json({ error: 'Internal server error' });
}

Development Mode

For local testing, enable dev mode in the SDK:

const sdk = new GamesFunSDK({
    dev: {
        enabled: true,
        mock: {
            wallet: {
                address: 'ED5nyyWEzpPPiWimP8vYm7sD7TD3LAt3Q3gRTWHzPJBY',
                privyId: '123'
            }
        }
    }
});

Best Practices

1. Token Storage

   • Don't store tokens in localStorage

   • Keep in memory only

   • Clear on logout/errors

2. Error Handling

   • Implement automatic token refresh

   • Clear invalid tokens

   • Provide clear error messages

3. Security

   • Always verify tokens server-side

   • Check token expiration

   • Validate issuer and algorithm

4. Development

   • Use dev mode for testing

   • Log auth errors in debug mode

   • Test token expiration handling

Next Steps

• Game Wallet - Learn about token transfers and validation

• Game Server - Set up your game server

• React Integration - Use with React components