Skip to main content

​
Overview

The WellPlayed React SDK uses OpenID Connect (OIDC) for authentication, powered by @axa-fr/react-oidc. This provides a secure, industry-standard authentication flow with support for refresh tokens.

​
Getting Your App Client ID

1

Access the Console

Navigate to the WellPlayed Console
2

Create or Select an App

Create a new application or select an existing one
3

Configure Redirect URIs

Add your application’s redirect URIs (e.g., https://yourapp.com/login)
4

Copy Client ID

Copy the App Client ID to use in your configuration
The redirect URI in your code must exactly match one of the redirect URIs configured in the WellPlayed Console.

​
Authentication Setup

​
Basic Configuration

Configure authentication by passing the wpAppConfig to the WellPlayedProvider: 
import { WellPlayedProvider } from '@well-played.gg/react-sdk';

const App = () => {
  return (
    <WellPlayedProvider
      organizationId="your-organization-id"
      wpAppConfig={{
        scope: "offline_access", // Enables refresh tokens
        client_id: "your-app-client-id",
        redirect_uri: `${window.location.protocol}//${window.location.host}/login`,
      }}
    >
      {/* Your app components */}
    </WellPlayedProvider>
  );
};

​
Understanding the Scope

​
scope
string
required
The OAuth 2.0 scopes for your application.Recommended value: "offline_access"This enables refresh tokens, allowing your application to:
  • Maintain user sessions across browser refreshes
  • Automatically renew access tokens in the background
  • Keep users logged in for extended periods

​
Redirect URI Configuration

The redirect URI is where users return after authentication: 
// Dynamic redirect URI based on current host
redirect_uri: `${window.location.protocol}//${window.location.host}/login`

// Or use a static URI
redirect_uri: "https://yourapp.com/login"
The redirect URI must:
  1. Match exactly with a URI configured in your App Client settings
  2. Include a path component (e.g., /login), not just the domain
  3. Use HTTPS in production environments

​
Using Authentication Hooks

​
useConnectedPlayer

Access the authenticated user’s profile, permissions, and authentication state: 
import { useConnectedPlayer } from '@well-played.gg/react-sdk';

const UserProfile = () => {
  const { 
    data, 
    loading, 
    authenticated, 
    login, 
    logout, 
    refetch 
  } = useConnectedPlayer();

  if (loading) return <div>Loading...</div>;
  
  if (!authenticated) {
    return <button onClick={login}>Sign In</button>;
  }

  return (
    <div>
      <h1>Welcome, {data?.getMyAccount?.profiles[0]?.username}!</h1>
      <button onClick={logout}>Sign Out</button>
    </div>
  );
};

​
Return Values

​
authenticated
boolean
Whether the user is currently authenticated.
​
loading
boolean
Whether the user data is being fetched.
​
data
object | undefined
The authenticated user’s account data.
​
login
() => void
Function to initiate the login flow.
​
logout
() => void
Function to log out the current user.
​
refetch
() => Promise<ApolloQueryResult>
Function to refetch the user’s account data.

​
Authentication Flow

1

User initiates login

User clicks a login button that calls the login() function from useConnectedPlayer
2

Redirect to WellPlayed

User is redirected to WellPlayed’s OAuth server for authentication
3

User authenticates

User logs in with their WellPlayed credentials
4

Redirect back to app

User is redirected back to your app’s redirect_uri with an authorization code
5

Token exchange

The SDK automatically exchanges the code for access and refresh tokens
6

Authenticated state

Your app now has access to the user’s profile and can make authenticated API calls

​
Protected Routes

Create protected routes that require authentication: 
import { useConnectedPlayer } from '@well-played.gg/react-sdk';
import { Navigate } from 'react-router-dom';

const ProtectedRoute = ({ children }: { children: React.ReactNode }) => {
  const { authenticated, loading } = useConnectedPlayer();

  if (loading) {
    return <div>Loading...</div>;
  }

  if (!authenticated) {
    return <Navigate to="/login" replace />;
  }

  return <>{children}</>;
};

// Usage
<Route path="/dashboard" element={
  <ProtectedRoute>
    <Dashboard />
  </ProtectedRoute>
} />

​
Accessing User Permissions

Check user permissions to control access to features: 
const { data } = useConnectedPlayer();

const userPermissions = data?.getMyAccount?.permissions || [];
const hasAdminAccess = userPermissions.some(
  perm => perm.resources.includes('admin')
);

if (hasAdminAccess) {
  // Show admin UI
}

​
Working with User Identities

Access linked identity providers: 
const { data } = useConnectedPlayer();

const identities = data?.getMyAccount?.identities || [];
const discordIdentity = identities.find(
  identity => identity.providerId === 'discord'
);

if (discordIdentity) {
  const discordUsername = discordIdentity.properties.find(
    prop => prop.property === 'username'
  )?.value;
}

​
Source Reference

Authentication implementation:
  • players.hook.ts:116-133 - useConnectedPlayer hook
  • players.hook.ts:89-114 - GraphQL query for user account
  • wp.provider.tsx:96-133 - Authentication provider integration

Build docs developers (and LLMs) love

Get started for freeTalk to us