Skip to main content

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
Immutable's Typescript SDK requires **Node v20** (Active LTS version) or **higher**. Node v20 can be installed via `nvm`.

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 install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node
Troubleshooting

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:

rm -Rf node_modules
npm cache clean --force
npm i

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,
};
info

Note: The environment argument can be one of the following:

EnvironmentDescription
Environment.SANDBOXThe default test network (currently, it is Sepolia)
Environment.PRODUCTIONThe 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
info

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.
info

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 CodeCauseResolution
INVALID_CONFIGURATIONThe environment configuration or OIDC Configuration is incorrectVerify 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.