How to Handle Authentication

This guide covers the GameGlue authentication flow and how to handle common authentication scenarios in your application.

The Authentication Flow

GameGlue uses OAuth 2.0 for authentication. Here's how it works:

1. Your app redirects to GameGlue login
2. User logs in and grants permission
3. User is redirected back to your app with a token
4. Your app exchanges the token for a session

The SDK handles most of this automatically.

Basic Authentication

The simplest authentication setup:

const ggClient = new GameGlue({
  clientId: 'your-client-id',
  redirect_uri: 'http://localhost:3000',
  scopes: ['msfs:read']
});

async function init() {
  // This checks for existing session AND handles OAuth callback
  const isAuthed = await ggClient.isAuthenticated();

  if (!isAuthed) {
    // Not logged in - redirect to login
    ggClient.login();
    return;
  }

  // User is authenticated
  const userId = ggClient.getUser();
  // Continue with your app...
}

init();

Handle the OAuth Callback

When users return from login, isAuthenticated() automatically handles the OAuth callback. Make sure it runs on page load:

// This MUST run when the page loads
// It detects the OAuth callback parameters and exchanges them for a session
const isAuthed = await ggClient.isAuthenticated();

If you're using a framework with routing, call this in your callback route:

// React example with React Router
function OAuthCallback() {
  useEffect(() => {
    async function handleCallback() {
      const isAuthed = await ggClient.isAuthenticated();
      if (isAuthed) {
        navigate('/dashboard');
      } else {
        navigate('/login-failed');
      }
    }
    handleCallback();
  }, []);

  return <div>Completing login...</div>;
}

Check Authentication State

Check if the user is currently authenticated:

const isAuthed = await ggClient.isAuthenticated();

if (isAuthed) {
  showDashboard();
} else {
  showLoginButton();
}

Get User Information

After authentication, get the user's ID:

const userId = ggClient.getUser();

You'll need this when creating listeners:

const listener = await ggClient.createListener({
  userId: userId,  // Required
  gameId: 'msfs'
});

Log Out

To log the user out:

ggClient.logout();

This clears the local session. The user will need to log in again to use your app.

Request Additional Scopes

If you need more permissions later (e.g., adding write access), update your scopes and have the user log in again:

// Initially only read access
const ggClient = new GameGlue({
  clientId: 'your-client-id',
  redirect_uri: 'http://localhost:3000',
  scopes: ['msfs:read']
});

// Later, when user wants to control the sim
function upgradeToWriteAccess() {
  // Update scopes
  ggClient.scopes = ['msfs:read', 'msfs:write'];

  // Log out and back in to get new permissions
  ggClient.logout();
  ggClient.login();
}

Sending commands requires the corresponding {gameId}:write scope. Without it, command requests are rejected.

Handle Session Expiration

Sessions can expire. Handle this gracefully:

listener.on('error', async (err) => {
  if (err.code === 'SESSION_EXPIRED') {
    // Session expired - re-authenticate
    const isAuthed = await ggClient.isAuthenticated();
    if (!isAuthed) {
      showMessage('Session expired. Please log in again.');
      ggClient.login();
    }
  }
});

Authentication with Multiple Games

If your app supports multiple games, request all needed scopes upfront:

const ggClient = new GameGlue({
  clientId: 'your-client-id',
  redirect_uri: 'http://localhost:3000',
  scopes: [
    'msfs:read',
    'msfs:write',
    'other-game:read'
  ]
});

Available Scopes

Scope	Description
msfs:read	Read telemetry from Microsoft Flight Simulator
msfs:write	Send commands to Microsoft Flight Simulator

Additional game scopes will be added as more games are supported.

Troubleshooting

See Troubleshooting Connection Issues for help with:

• Login redirect loops
• "Unauthorized" errors
• Session problems