@imtbl/auth

Authentication utilities for the Immutable SDK.

Installation

npm install @imtbl/auth

Overview

This package provides two ways to handle Immutable authentication:

1. Auth Class - Full-featured authentication with session managed on client side.
2. Standalone Login Functions - Stateless login functions for use with external session managers (e.g., NextAuth)

Standalone Login Functions

For Next.js applications using NextAuth, use the standalone login functions. These handle OAuth flows and return tokens without managing session state.

loginWithPopup

Opens a popup window for authentication and returns tokens when complete.

import { loginWithPopup } from '@imtbl/auth';
import { signIn } from 'next-auth/react';

async function handleLogin() {
  const tokens = await loginWithPopup({
    clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
    redirectUri: `${window.location.origin}/callback`,
  });
  
  // Sign in to NextAuth with the tokens
  await signIn('immutable', {
    tokens: JSON.stringify(tokens),
    redirect: false,
  });
}

loginWithRedirect

Redirects the page to the authentication provider. Use handleLoginCallback on the callback page.

import { loginWithRedirect } from '@imtbl/auth';

function handleLogin() {
  loginWithRedirect({
    clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
    redirectUri: `${window.location.origin}/callback`,
  });
}

handleLoginCallback

Handles the OAuth callback and exchanges the authorization code for tokens.

import { handleLoginCallback } from '@imtbl/auth';
import { signIn } from 'next-auth/react';

// In your callback page
async function processCallback() {
  const tokens = await handleLoginCallback({
    clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
    redirectUri: `${window.location.origin}/callback`,
  });
  
  if (tokens) {
    await signIn('immutable', {
      tokens: JSON.stringify(tokens),
      redirect: false,
    });
    // Redirect to home or dashboard
    window.location.href = '/';
  }
}

LoginConfig

Configuration options for standalone login functions:

interface LoginConfig {
  /** Your Immutable application client ID */
  clientId: string;
  /** The OAuth redirect URI for your application */
  redirectUri: string;
  /** Optional separate redirect URI for popup flows */
  popupRedirectUri?: string;
  /** OAuth audience (default: "platform_api") */
  audience?: string;
  /** OAuth scopes (default: "openid profile email offline_access transact") */
  scope?: string;
  /** Authentication domain (default: "https://auth.immutable.com") */
  authenticationDomain?: string;
}

TokenResponse

The token data returned from successful authentication:

interface TokenResponse {
  /** OAuth access token for API calls */
  accessToken: string;
  /** OAuth refresh token for token renewal */
  refreshToken?: string;
  /** OpenID Connect ID token */
  idToken?: string;
  /** Unix timestamp (ms) when the access token expires */
  accessTokenExpires: number;
  /** User profile information */
  profile: {
    sub: string;
    email?: string;
    nickname?: string;
  };
  /** zkEVM wallet information if available */
  zkEvm?: {
    ethAddress: string;
    userAdminAddress: string;
  };
}

Auth Class

For applications that need full authentication management (like the Passport SDK), use the Auth class:

import { Auth } from '@imtbl/auth';

const auth = new Auth({
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  scope: 'openid profile email offline_access transact',
});

// Login with popup
const user = await auth.login();

// Get current user
const user = await auth.getUser();

// Logout
await auth.logout();

Integration with NextAuth

For a complete Next.js authentication setup, use this package with:

• @imtbl/auth-next-server - Server-side NextAuth configuration
• @imtbl/auth-next-client - Client-side components and hooks

See those packages for full integration documentation.