Install and initialise
Before you can begin using Passport, you must install the Immutable SDK and initialise the Passport Client. The SDK Passport Module enables games & third-party applications to leverage Immutables authentication and wallet functionalities.
Before you can begin using Passport, you must install the Immutable SDK and initialise the Passport Client. The SDK Passport Module enables games & third-party applications to leverage Immutables authentication and wallet functionalities.
1. Install
Prerequisites
Node Version 20 or later
To install nvm follow these instructions. Once installed, run:
nvm install --lts
- (Optional) To enable Code Splitting (importing only the SDK modules you need) there are additional prerequisites.
Install the Immutable SDK
Run the following command in your project root directory.
- npm
- yarn
npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node
yarn add --dev @imtbl/sdk
# if necessary, install dependencies
yarn add --dev typescript ts-node
The Immutable SDK is still in early development. If experiencing complications, use the following commands to ensure the most recent release of the SDK is correctly installed:
- npm
- yarn
rm -Rf node_modules
npm cache clean --force
npm i
rm -Rf node_modules
yarn cache clean
yarn install
2. Initialise Passport
Next, we'll need to initialise the Passport client. The Passport constructor accepts a PassportModuleConfiguration
object, which has the following interface:
import { config, passport } from '@imtbl/sdk';
// passport.PassportModuleConfiguration
interface PassportModuleConfiguration {
baseConfig: config.ImmutableConfiguration;
clientId: string;
logoutRedirectUri?: string; // defaults to first logout redirect URI specified in the Immutable Hub
logoutMode?: 'redirect' | 'silent'; // defaults to 'redirect'
redirectUri: string;
scope?: string;
audience?: string;
}
2.1 baseConfig
An instance of an ImmutableConfiguration, which defines shared configuration across all the Immutable modules, such
as the environment. This can be initialised as follows:
import { config } from '@imtbl/sdk';
const PUBLISHABLE_KEY = 'YOUR_PUBLISHABLE_KEY'; // Replace with your Publishable Key from the Immutable Hub
const baseConfig = {
environment: config.Environment.PRODUCTION,
publishableKey: PUBLISHABLE_KEY,
};
Note: The environment argument can be one of the following:
| Environment | Description |
|---|---|
| Environment.SANDBOX | The default test network (currently, it is Sepolia) |
| Environment.PRODUCTION | The Ethereum mainnet network |
2.2 clientId
The unique identifier of the application that was registered in the Immutable Hub
2.3 redirectUri
The URI of your application that users will be redirected to after successfully authenticating. This value must match
one of the Callback URLs that have been set against your client in the Immutable Hub. If no value is
specified, then Passport will default to the redirect logout mode.
2.4 logoutRedirectUri
The URI of your application that users will be redirected to after successfully logging out. This value must match one of the Logout URL's that have been set against your client in the Immutable Hub. If no value is specified, then Passport will default to your Passport client's first logout redirect URI.
2.5 audience
A string containing the audience(s) that the issued token is intended for, with each audience being separated by a space. Passport currently supports the following audiences:
platform_api: The identifier for the Immutable protocol APIs
Note: The platform_api audience is required in order to interact with the Immutable protocol.
2.6 scope
A string containing the scope(s) that specify what access privileges are being requested, with each scope being separated by a space. The following custom scopes are supported:
transact: Allows the authenticating application to interact with the users Passport wallet.
In addition to the above, the following standard OpenID Connect (OIDC) scopes are strongly recommended:
openid: Informs the Authorization Server that the client is making an OpenID connect request. Without this scope, users will not be able to authenticate.offline_access: Requests that an OAuth 2.0 Refresh Token be issued. The Refresh Token is used by Passport to automatically rotate expired tokens and during registration to initialise the user's wallet. Without this scope, token rotation, user registration and a number of other operations will fail.email: Requests that the client gains access to the users email address. Without this scope, the users email address will not be available to the client.
Note: The transact, openid & offline_access scopes are all currently required to correctly interact with Passport.
2.7 Example initialisation
import { config, passport } from '@imtbl/sdk';
const passportInstance = new passport.Passport({
baseConfig: {
environment: config.Environment.SANDBOX, // or Environment.PRODUCTION
publishableKey: '<YOUR_PUBLISHABLE_KEY>', // replace with your publishable API key from Hub
},
clientId: '<YOUR_CLIENT_ID>', // replace with your client ID from Hub
redirectUri: 'https://localhost:3000/redirect', // replace with one of your redirect URIs from Hub
logoutRedirectUri: 'https://localhost:3000/logout', // replace with one of your logout URIs from Hub
audience: 'platform_api',
scope: 'openid offline_access email transact',
popupOverlayOptions: {
disableGenericPopupOverlay: false, // Set to true to disable the generic pop-up overlay
disableBlockedPopupOverlay: false, // Set to true to disable the blocked pop-up overlay
}
});
Note that the Passport constructor may throw the following error:
| Error Code | Cause | Resolution |
|---|---|---|
| INVALID_CONFIGURATION | The environment configuration or OIDC Configuration is incorrect | Verify that you are passing an environment configuration and OIDC configuration, and that all the mandatory properties have been set |
3. Next steps
You have now successfully installed and initialised the Passport module. The next step is to enable users' identity via a user's Passport account in your application.