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.

Sections

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 >18
Immutable's Typescript SDK requires **Node v18** (Active LTS version) or **higher**. Node v18 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. See the Code Splitting section below.

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