Authentication (Advanced)

Advanced topics covering player authentication flows, teams, and security features.

Keep API Keys Secret

Never commit API keys to version control or expose them in client-side code.

API Key Types

Private API Keys

• Full access to your team's resources
• Use on your backend server only
• Can create and manage players
• Never expose in client-side code

Public API Keys - Service Account

• Limited to player login only
• Safe to embed in your app
• Cannot create or modify resources
• Used for end-user authentication

API Authentication

For programmatic access, generate API keys from Account Settings:

curl -X POST https://pug.stg.uglabs.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your-api-key-here"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600
}

Token Expiration

Access tokens expire after 60 minutes. Refresh them before expiration:

const getValidToken = async () => {
  const now = Date.now();
  if (!accessToken || tokenExpiry < now + 5 * 60 * 1000) {
    // Refresh 5 minutes before expiration
    const response = await fetch('/api/login', {
      method: 'POST',
      // ... authentication details
    });
    const data = await response.json();
    accessToken = data.access_token;
    tokenExpiry = now + (data.expires_in * 1000);
  }
  return accessToken;
};

Player Authentication

Players authenticate using a public API key and a federated ID:

// Client-side login
const response = await fetch('https://pug.stg.uglabs.app/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: PUBLIC_API_KEY,      // Safe to embed
    federated_id: federatedId     // Unique per player
  })
});

const { access_token } = await response.json();

Quick Start

See Player Onboarding for complete registration examples.

Teams

Teams organize resources and enable collaboration:

• Unique names: Globally unique across the platform
• Resource isolation: Complete separation between teams
• Multi-team support: Users can belong to multiple teams

When working with multiple teams, specify which one:

{
  api_key: 'your-api-key',
  team_name: 'my-team'  // Optional
}

Player Authentication Flow

The player authentication process involves three stages:

Step 1: Create Service Account

Create a public API key with playerLogin role:

1. Go to Console > Service Accounts
2. Click "Create Service Account"
3. Select playerLogin role
4. Copy the generated API key

Step 2: Create Players

When a user registers in your system, create a player in UG Labs:

// Your backend server
const createPlayer = async (userEmail) => {
  const response = await fetch('https://pug.stg.uglabs.app/api/players', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${PRIVATE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      external_id: userEmail  // Your unique identifier
    })
  });

  const data = await response.json();
  return data.federated_id;  // Store this securely
};

External ID

The external_id can be any unique identifier: email, username, device ID, etc.

Step 3: Player Login

Players authenticate using the public API key and their federated ID:

// Client-side (mobile app, web app, etc.)
const loginPlayer = async (federatedId) => {
  const response = await fetch('https://pug.stg.uglabs.app/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      api_key: PUBLIC_API_KEY,
      federated_id: federatedId
    })
  });

  const { access_token } = await response.json();
  return access_token;
};

Security Features

The federated ID system provides key security benefits:

Prevents Uncontrolled Player Creation

• Players can only be created with a private API key (backend secret)
• Public API keys cannot create players
• Prevents abuse and unauthorized account creation

Prevents Player Impersonation

• External IDs (emails, usernames) are not used directly for authentication
• Federated IDs are globally unique secrets
• Cannot be guessed or enumerated

Federated ID Security

Never expose federated IDs publicly. They are authentication credentials equivalent to passwords.

Player vs. User Comparison

Aspect	User (Developer)	Player (End-User)
Access	Full API access	Interaction endpoint only
Resources	Can create/modify	Read-only
Isolation	Team-scoped	Completely isolated
Authentication	API key or SSO	Public API key + Federated ID

Best Practices

Security

• Never expose private API keys in client code
• Store federated IDs securely (treat like passwords)
• Always use HTTPS for API calls
• Rotate API keys periodically

Development

• Use separate teams for dev/staging/production
• Use different API keys per environment
• Test token expiration scenarios
• Monitor authentication failures

Next Steps

• Player Onboarding - Learn about player registration strategies
• Authentication - Back to authentication basics
• Interaction Flow - Learn how to use authenticated connections
• WebSocket Protocol - Understand the message protocol