Set up your Passport client in Immutable Hub to get the credentials needed for authentication.
Create Passport Client
Step-by-step guide to creating a Passport client, configuring redirect URIs, and getting your Client ID
You’ll need:
Client ID from your Passport client in Hub
Publishable Key from your Hub project settings
These values are required to initialize Passport in the next section.
Passport Credentials Reference
Field
Type
Description
Client ID
Provided by Hub
Unique identifier for your application. Copy from Hub and use in SDK initialization.
Publishable Key
Provided by Hub
Public key safe for client-side code. Copy from Hub project settings.
Application Type
You configure
Select Web for TypeScript/web apps, Native for Unity/Unreal games.
Application Name
You configure
Identifier for your project inside Passport (e.g., “My Game”).
Redirect URIs
You configure
Where users land after successful authentication. Must exactly match redirectUri in your code. Examples: http://localhost:3000/redirect (web), mygame://callback (native).
Logout URIs
You configure
Where users land after logout. Must exactly match logoutRedirectUri in your code. Examples: http://localhost:3000/logout (web), mygame://logout (native).
Passport uses OpenID Connect (OIDC). Redirect URIs must be exact matches—wildcards aren’t supported for security reasons. Register multiple URIs for different environments (localhost, staging, production).
For full setup details including server utilities and route protection, see the Next.js integration guide.
import { Auth } from '@imtbl/auth';export const auth = new Auth({ clientId: process.env.NEXT_PUBLIC_CLIENT_ID || 'YOUR_CLIENT_ID', redirectUri: 'http://localhost:3000/redirect', logoutRedirectUri: 'http://localhost:3000/logout', logoutMode: 'redirect', // or 'silent' - see Logout section for details audience: 'platform_api', scope: 'openid offline_access email transact',});
Scopes
Scope
Required
Description
openid
✅ Yes
Returns user ID (sub claim)
offline_access
✅ Yes
Enables refresh tokens for persistent sessions
email
Optional
Access to user’s email address
transact
Optional
Permission to sign transactions
using Immutable.Passport;public class GameManager : MonoBehaviour{ private Passport passport; async void Start() { // Initialize Passport passport = await Passport.Init( clientId: "YOUR_CLIENT_ID", environment: Immutable.Passport.Model.Environment.SANDBOX, redirectUri: "mygame://callback", logoutRedirectUri: "mygame://logout" ); // Restore session if available if (await passport.HasCredentialsSaved()) { await passport.Login(useCachedSession: true); } }}
#pragma once#include "Immutable/ImmutableSubsystem.h"#include "Immutable/ImmutablePassport.h"#include "PassportQuickStartSubsystem.generated.h"UCLASS()class UPassportQuickStartSubsystem : public UGameInstanceSubsystem{ GENERATED_BODY()public: virtual void Initialize(FSubsystemCollectionBase& Collection) override { Super::Initialize(Collection); auto Subsystem = Collection.InitializeDependency<UImmutableSubsystem>(); Subsystem->WhenReady(this, &UPassportQuickStartSubsystem::OnPassportReady); }private: void OnPassportReady(TWeakObjectPtr<UImtblJSConnector> JSConnector) { auto Passport = GetPassport(); if (!Passport) { UE_LOG(LogTemp, Error, TEXT("Failed to get Passport instance")); return; } Passport->Initialize(FImmutablePassportInitData { TEXT("YOUR_CLIENT_ID"), TEXT("mygame://callback"), TEXT("mygame://logout"), TEXT("sandbox"), false }, UImmutablePassport::FImtblPassportResponseDelegate::CreateUObject(this, &UPassportQuickStartSubsystem::OnPassportInitialized)); } void OnPassportInitialized(FImmutablePassportResult Result) { if (!Result.Success) { UE_LOG(LogTemp, Error, TEXT("Passport Initialization Failed: %s"), *Result.Error); return; } UE_LOG(LogTemp, Log, TEXT("Passport Initialized Successfully")); } UImmutablePassport* GetPassport() const { if (GetGameInstance()) { auto Subsystem = GetGameInstance()->GetSubsystem<UImmutableSubsystem>(); if (Subsystem) { return Subsystem->GetPassport().Get(); } } return nullptr; }};
Login
Next.js
TypeScript
Unity
Unreal
The useLogin hook provides embedded, popup, and redirect login flows. All functions accept an optional config; when omitted, sandbox defaults are used.
Embedded Login
Shows an in-page modal for login method selection — no popup window required:
const { loginWithRedirect } = useLogin();// Navigates away from the page for OAuth authenticationawait loginWithRedirect(loginConfig);
Direct Login Options
Skip the login method selection screen and go directly to a specific provider:
import { MarketingConsentStatus } from '@imtbl/auth-next-client';const { loginWithPopup } = useLogin();// Direct to Google loginawait loginWithPopup(config, { directLoginOptions: { directLoginMethod: 'google', marketingConsentStatus: MarketingConsentStatus.OptedIn, },});// Direct to email login with marketing consentawait loginWithPopup(config, { directLoginOptions: { directLoginMethod: 'email', email: 'user@example.com', marketingConsentStatus: MarketingConsentStatus.OptedIn, },});
Option
Description
directLoginMethod
The authentication provider (email, google, or apple)
email
Required when directLoginMethod is email
marketingConsentStatus
Marketing consent (OptedIn or Unsubscribed)
Headless Login
For a more streamlined user experience, the standard Passport login prompt can be bypassed by providing the directLoginOptions parameter to the login method. This allows you to render a customised authentication prompt within your own application.Once an authentication option (email, Google, Apple, or Facebook) is passed to the login method, a popup will be opened so that the user can authenticate securely.
// Headless login with emailconst user = await auth.login({ directLoginOptions: { directLoginMethod: 'email', email: 'user@example.com', marketingConsentStatus: 'opted_in' }});// Headless login with specific providerconst user = await auth.login({ directLoginOptions: { directLoginMethod: 'google', // or 'apple', 'facebook' marketingConsentStatus: 'opted_in' }});
Option
Description
directLoginMethod
The authentication provider (email, google, apple, or facebook)
email
Required when directLoginMethod is email, specifies the user’s email address
marketingConsentStatus
Marketing consent setting (opted_in or unsubscribed)
Login with EthersJS
Integrates Passport authentication with EthersJS for wallet connection and interaction.
This implementation uses EthersJS’s BrowserProvider to interact with the Passport provider. It requests user accounts and manages the connection state, displaying the connected account address when successful.
Identity-only Login
The login method can be used to log in a user and retrieve their profile information without connecting to Immutable zkEVM.
const profile: User | null = await auth.login();
This will prompt the user to select an authentication option from within an iFrame, and open a popup to securely complete the authentication process.
Embedded Login
The PassportUI prefab provides a seamless, embedded authentication experience that keeps users within your application. This approach offers better user experience and higher conversion rates.
Setting up the PassportUI Prefab
Platform
WebView Package
Windows
Volt Unity Web Browser (UWB) - no additional packages required
iOS/Android/macOS
Vuplex WebView (paid third-party product)
1. Add the PassportUI Prefab to Your SceneChoose the appropriate prefab for your target platform:
PassportLogin_Windows.prefab - For Windows builds using UWB
PassportLogin_Vuplex.prefab - For iOS, Android, and macOS builds using Vuplex
2. Initialize PassportUI
public class MyAuthScript : MonoBehaviour{ public PassportUI passportUI; async void Start() { // Initialize with existing Passport instance await passportUI.InitializeWithPassport(Passport.Instance); // Or initialize PassportUI with automatic Passport creation // (uses the clientId/environment/URIs set in the Inspector) await passportUI.InitializeWithPassport(); }}
3. Handle Authentication Events
void Start(){ // Subscribe to authentication events Passport.Instance.OnAuthEvent += OnAuthEvent;}private void OnAuthEvent(PassportAuthEvent authEvent){ switch (authEvent) { case PassportAuthEvent.LoginPKCESuccess: Debug.Log("User logged in successfully"); break; case PassportAuthEvent.LogoutPKCESuccess: Debug.Log("User logged out"); break; case PassportAuthEvent.ReloginSuccess: Debug.Log("User re-logged in with cached credentials"); break; }}
For iOS, Android, and macOS, the embedded WebView requires Vuplex WebView, a paid third-party package. Alternatively, use Standard Login which doesn’t require any WebView.
Headless Login
For a more streamlined user experience, bypass the standard Passport login prompt by providing the DirectLoginOptions parameter:
// Customized login with emailawait passport.Login(directLoginOptions: new DirectLoginOptions( DirectLoginMethod.Email, "user@example.com", MarketingConsentStatus.OptedIn));// Customized login with specific providerawait passport.Login(directLoginOptions: new DirectLoginOptions( DirectLoginMethod.Google // or Apple, Facebook));
Option
Description
DirectLoginMethod
The authentication provider (Email, Google, Apple, or Facebook)
email
Required when DirectLoginMethod is Email, specifies the user’s email address
marketingConsentStatus
Marketing consent setting (OptedIn or Unsubscribed)
Standard Login
Use the basic Login() method to show the standard Passport login prompt:
await passport.Login();
This will open an external browser window on desktop or an in-app browser on mobile devices, prompting the user to select an authentication option and complete the authentication process securely.
Stored Credentials
Once the gamer is connected to Passport, the SDK will store credentials (access, ID, and refresh tokens). Use Login(useCachedSession: true) to re-login using saved credentials.
After Passport initialization completes, call PerformLogin() to authenticate the user.
// Add to your subsystem:public: void PerformLogin() { auto Passport = GetPassport(); if (!Passport) { return; } Passport->Connect ( true, UImmutablePassport::FImtblPassportResponseDelegate::CreateUObject(this, &UPassportQuickStartSubsystem::OnLoginComplete) ); }private: void OnLoginComplete(FImmutablePassportResult Result) { if (!Result.Success) { UE_LOG(LogTemp, Error, TEXT("Login Failed: %s"), *Result.Error); return; } UE_LOG(LogTemp, Log, TEXT("Login Successful")); }void OnPassportInitialized(FImmutablePassportResult Result){ if (!Result.Success) return; UE_LOG(LogTemp, Log, TEXT("Passport Initialized Successfully")); PerformLogin();}
Headless Login
For a more streamlined user experience, bypass the standard Passport login prompt by providing the DirectLoginOptions parameter. Once an authentication option (email, Google, Apple, or Facebook) is passed, a popup will be opened so that the user can authenticate securely.
// Add to your subsystem:public: void PerformHeadlessLogin() { auto Passport = GetPassport(); if (!Passport) { return; } // Customised login with email Passport->Connect ( true, UImmutablePassport::FImtblPassportResponseDelegate::CreateUObject(this, &UPassportQuickStartSubsystem::OnLoginComplete), {.DirectLoginMethod = EImmutableDirectLoginMethod::Email} ); }private: void OnLoginComplete(FImmutablePassportResult Result) { if (!Result.Success) { UE_LOG(LogTemp, Error, TEXT("Login Failed: %s"), *Result.Error); return; } UE_LOG(LogTemp, Log, TEXT("Login Successful")); }void OnPassportInitialized(FImmutablePassportResult Result){ if (!Result.Success) return; UE_LOG(LogTemp, Log, TEXT("Passport Initialized Successfully")); PerformHeadlessLogin();}
Option
Description
DirectLoginMethod
The authentication provider (Email, Google, Apple, or Facebook)
Email
Required when DirectLoginMethod is Email, specifies the user’s email address
MarketingConsentStatus
Marketing consent setting (Opted_In or Unsubscribed)
Standard Login
Use the basic Login() method without any parameters to show the standard Passport login prompt:
This will open an external browser window on desktop or an in-app browser on mobile devices, prompting the user to select an authentication option and complete the authentication process securely.
Stored Credentials
Once the gamer is connected to Passport, the SDK will store credentials (access, ID, and refresh tokens).You can use the HasStoredCredentials async action to check if the gamer has stored credentials before deciding whether to show login options in your UI.
The HasStoredCredentials async action is currently Blueprint-compatible only. For C++, use the Passport instance methods directly.
Handle the Callback
On your redirect URI page, process the authentication callback:
The CallbackPage component handles both redirect and popup flows automatically. For popup logins, it communicates tokens back to the parent window and closes itself.
// Get user info from the ID tokenconst userInfo = await auth.getUserInfo();console.log({ userId: userInfo.sub, // Unique Passport user ID email: userInfo.email, // If email scope granted emailVerified: userInfo.email_verified,});
var userInfo = await passport.GetUserInfo();Debug.Log($"User ID: {userInfo.Sub}");Debug.Log($"Email: {userInfo.Email}");
// Add to your subsystem:private: void OnLoginComplete(FImmutablePassportResult Result) { if (!Result.Success) { UE_LOG(LogTemp, Error, TEXT("Login Failed: %s"), *Result.Error); return; } UE_LOG(LogTemp, Log, TEXT("Login Successful")); auto Passport = GetPassport(); // Get user email Passport->GetEmail(UImmutablePassport::FImtblPassportResponseDelegate::CreateWeakLambda(this, [this](FImmutablePassportResult EmailResult) { if (EmailResult.Success) { FString Email = UImmutablePassport::GetResponseResultAsString(EmailResult.Response); UE_LOG(LogTemp, Log, TEXT("User Email: %s"), *Email); } })); // Get user wallet address Passport->GetAddress(UImmutablePassport::FImtblPassportResponseDelegate::CreateWeakLambda(this, [this](FImmutablePassportResult AddressResult) { if (AddressResult.Success) { FString Address = UImmutablePassport::GetResponseResultAsString(AddressResult.Response); UE_LOG(LogTemp, Log, TEXT("Wallet Address: %s"), *Address); } })); }
Note: The Unreal SDK provides separate methods (GetEmail, GetAddress) rather than a unified GetUserInfo() method. See Get ID Token and Get Access Token sections for retrieving tokens.
Session Management
Check If Logged In
Next.js
TypeScript
Unity
Unreal
Always use isAuthenticated from useImmutableSession to determine if a user is logged in.
'use client';import { useImmutableSession } from '@imtbl/auth-next-client';function ProtectedContent() { const { isAuthenticated, isLoading } = useImmutableSession(); if (isLoading) return <div>Loading...</div>; if (!isAuthenticated) return <div>Please log in</div>; return <div>Protected content</div>;}
Do not use !!session or status === 'authenticated' to check auth state. A session object can exist with expired or invalid tokens, and status does not account for token-level errors like RefreshTokenError.
isAuthenticated validates all of the following:
NextAuth reports 'authenticated' status
The session object exists
A valid access token is present in the session
No session-level error exists (such as RefreshTokenError)
It also handles transient states gracefully — during session refetches (window focus) or manual refreshes (after wallet registration via getUser(true)), isAuthenticated remains true if the user was previously authenticated, preventing UI flicker.
// Correctconst { isAuthenticated } = useImmutableSession();if (!isAuthenticated) return <div>Please log in</div>;// Incorrect -- session can exist with expired/invalid tokensconst { session } = useImmutableSession();if (!session) return <div>Please log in</div>;// Incorrect -- status doesn't account for token errorsconst { status } = useImmutableSession();if (status !== "authenticated") return <div>Please log in</div>;
async function isLoggedIn(): Promise<boolean> { return auth.isLoggedIn();}
// Add to your subsystem:public: void CheckStoredCredentials() { auto Passport = GetPassport(); if (!Passport) { return; } Passport->HasStoredCredentials(UImmutablePassport::FImtblPassportResponseDelegate::CreateUObject(this, &UPassportQuickStartSubsystem::OnCredentialsChecked)); }private: void OnCredentialsChecked(FImmutablePassportResult Result) { if (Result.Success) { UE_LOG(LogTemp, Log, TEXT("Stored Credentials Found - Proceeding to Login")); } else { UE_LOG(LogTemp, Log, TEXT("No Stored Credentials - New Login Required")); } }
Get Access Token
For authenticated API calls to your backend:
Next.js
TypeScript
Unreal
getAccessToken() returns a guaranteed-fresh access token. If the current token is valid it returns immediately; if expired, it triggers a server-side refresh and blocks until the fresh token is available. Multiple concurrent calls share a single refresh request.
const accessToken = await auth.getAccessToken();// Use in API requestsconst response = await fetch('/api/user/inventory', { headers: { Authorization: `Bearer ${accessToken}`, },});
// Add to your subsystem:private: void OnLoginComplete(FImmutablePassportResult Result) { if (!Result.Success) { UE_LOG(LogTemp, Error, TEXT("Login Failed: %s"), *Result.Error); return; } UE_LOG(LogTemp, Log, TEXT("Login Successful")); auto Passport = GetPassport(); Passport->GetAccessToken(UImmutablePassport::FImtblPassportResponseDelegate::CreateWeakLambda(this, [this](FImmutablePassportResult AccessTokenResult) { if (AccessTokenResult.Success) { FString AccessToken = UImmutablePassport::GetResponseResultAsString(AccessTokenResult.Response); // Use access token for authenticated API requests to your backend UE_LOG(LogTemp, Log, TEXT("Access Token: %s"), *AccessToken); } })); }
Token Refresh
Automatic Refresh
The server-side JWT callback automatically refreshes tokens when the access token expires. This happens transparently during any session access.
Force Refresh
After operations that update user claims on the identity provider (such as zkEVM wallet registration), force a token refresh to get the updated data:
const { getUser } = useImmutableSession();async function handleRegistration() { // ... after zkEVM registration completes const user = await getUser(true); console.log("Updated zkEvm:", user?.zkEvm);}
Get ID Token
The ID token contains user identity claims:
Next.js
TypeScript
Unreal
The ID token is not stored in the session cookie (to stay within CDN header size limits). Use getUser() to access it — the client persists it in localStorage automatically.
'use client';import { useImmutableSession } from '@imtbl/auth-next-client';function GetIdToken() { const { getUser } = useImmutableSession(); async function handleGetToken() { const user = await getUser(); console.log('ID Token:', user?.idToken); } return <button onClick={handleGetToken}>Get ID Token</button>;}
The useLogout hook performs federated logout — it clears both the local NextAuth session and the upstream Immutable/Auth0 session by redirecting to the logout endpoint. This is important when using social logins like Google: without federated logout, the auth server caches the social session, so users clicking “Login” again would be automatically logged in with the same account instead of being prompted to choose.