Prerequisites
Create Passport Client
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
- Client ID from your Passport client in Hub
- Publishable Key from your Hub project settings
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).
Installation
Install the Immutable SDK for your platform to get started with Passport:TypeScript
Install via npm or yarn
Unity
Install via Package Manager
Unreal
Install Passport plugin in your Unreal project
Initialize Passport
- TypeScript
- Unity
- Unreal
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 |
Login
- TypeScript
- Unity
- Unreal
Headless Login
For a more streamlined user experience, the standard Passport login prompt can be bypassed by providing thedirectLoginOptions 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.| 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.Identity-only Login
Thelogin method can be used to log in a user and retrieve their profile information without connecting to Immutable zkEVM.Handle the Callback
On your redirect URI page, process the authentication callback:- React
- Vanilla JS
Get User Information
User Profile
- TypeScript
- Unity
- Unreal
Session Management
Check If Logged In
- TypeScript
- Unity
- Unreal
Get Access Token
For authenticated API calls to your backend:- TypeScript
- Unreal
Get ID Token
The ID token contains user identity claims:- TypeScript
- Unreal
Logout
- TypeScript
- Unity
- Unreal
Default behavior - logs out without redirecting.
Logout with Redirect
To redirect users after logout, configurelogoutMode: 'redirect' at initialization, then call logout:Error Handling
Common Logout Issues:| Error | Cause | Solution |
|---|---|---|
| Logout callback timeout | Silent logout page didn’t load | Verify logoutRedirectUri is accessible |
| Wallet still connected | Cleanup order wrong | Disconnect wallet before passport.logout() |
| Session persists (Unreal) | Soft logout used | Set DoHardLogout: true |
Backend JWT Validation
Validate Passport JWTs on your server to secure API endpoints.Node.js with jose
Express Middleware
JWT Claims Reference
| Claim | Type | Description |
|---|---|---|
sub | string | Unique Passport user ID |
iss | string | Always https://auth.immutable.com/ |
aud | string | Your audience (e.g., platform_api) |
exp | number | Expiration timestamp |
iat | number | Issued at timestamp |
email | string | User’s email (if scope granted) |
email_verified | boolean | Whether email is verified |
Error Handling
Handle authentication errors gracefully to provide better user experience:Common Error Types
| Error Type | Description | Recommended Action |
|---|---|---|
AUTHENTICATION_ERROR | Login or authentication failed | Ask user to try again or use different provider |
USER_REGISTRATION_ERROR | User registration failed | Check if user already exists or retry |
WALLET_CONNECTION_ERROR | Failed to connect wallet | Retry connection or check network |
INVALID_CONFIGURATION | Invalid Passport configuration | Verify clientId and redirectUri |