Auth Manager Setup

Overview & Key Concepts

The Auth Manager is responsible for managing authentication state and session persistence in your Lit Protocol application. It handles the storage and retrieval of authentication credentials, enabling users to maintain active sessions across page refreshes and application restarts without re-authenticating.

What the Auth Manager Stores

When you authenticate with Lit Protocol, the Auth Manager caches critical authentication data locally:

Session Key Pair: A temporary cryptographic key pair that represents your current session with Lit Protocol:

Public key - Shared with Lit nodes to identify your session

Secret key (private key) - Kept securely in local storage, never transmitted

Delegation AuthSig (Inner Auth Sig): A cryptographic attestation from the Lit Protocol nodes that authorizes your session key to perform operations on behalf of your PKP

Install the SDK

Run the following command to install the SDK and the required viem peer dependency:

npm i @lit-protocol/auth viem

yarn add @lit-protocol/auth viem

pnpm add @lit-protocol/auth viem

bun add @lit-protocol/auth viem

viem must be installed as a dependency because the Lit JS SDK does not bundle it.

Choose Storage Plugin

Choose the appropriate storage plugin based on your environment and requirements, then create your Auth Manager instance.

import { createAuthManager, storagePlugins } from "@lit-protocol/auth";

const authManager = createAuthManager({
  storage: storagePlugins.localStorage({
    appName: "my-app",
    networkName: "naga-dev",
  }),
});

import { createAuthManager, storagePlugins } from "@lit-protocol/auth";

const authManager = createAuthManager({
  storage: storagePlugins.localStorageNode({
    appName: "my-node-app",
    networkName: "naga-dev",
    storagePath: "./lit-auth-storage",
  }),
});

import { createAuthManager } from "@lit-protocol/auth";

// Custom storage plugin example
const customStorage = {
  async write({ address, authData }) {
    // Your custom write logic
    await myDatabase.set(`lit-auth:${address}`, authData);
  },
  async read({ address }) {
    // Your custom read logic
    return await myDatabase.get(`lit-auth:${address}`);
  },
  async writeInnerDelegationAuthSig({ publicKey, authSig }) {
    // Store delegation auth signature
    await myDatabase.set(`lit-delegation:${publicKey}`, authSig);
  },
  async readInnerDelegationAuthSig({ publicKey }) {
    // Retrieve delegation auth signature
    return await myDatabase.get(`lit-delegation:${publicKey}`);
  },
  // ... implement other required methods
};

const authManager = createAuthManager({
  storage: customStorage,
});

Storage Options Comparison

Choose your storage plugin based on where your application runs and how you want to manage session data.

Storage Type	Persistence	Use Case	Environment
localStorage	Survives page refresh & browser restart	Best for most web apps - sessions persist across browser restarts without additional setup	Browser
localStorageNode	File-based persistent storage	Ideal for CLI tools, backend services, or automated scripts that need to maintain sessions	Node.js only
custom	Depends on implementation	Use when you need centralized session management, enhanced security, multi-device sync, or database storage	Custom

SDK

Getting Started

Authentication

Core API Methods

PKP Wallet Management

Utilities

Reference

Resources

Guides

FAQ

Overview & Key Concepts

What the Auth Manager Stores

Storage Options Comparison

​Overview & Key Concepts

​What the Auth Manager Stores

​Storage Options Comparison

Overview & Key Concepts

What the Auth Manager Stores

Storage Options Comparison