Skip to main content
💰 Need Test Tokens? Visit the Chronicle Yellowstone Faucet to get test tokens for your EOA account.

​
Overview

The Lit Protocol Auth Services package helps you run the infrastructure required to mint Programmable Key Pairs (PKPs) and power OAuth-based sign-in flows.
  • Auth Service: Handles PKP minting for supported auth methods and exposes APIs consumed by the Lit JS SDK.
  • Login Server: Manages OAuth flows (Google, Discord, etc.) and issues short-lived session tokens that the Auth Service consumes.

​
Hosted Auth Services

Lit hosts default Auth Service instances so you can build without deploying infrastructure on day one. Point your application to the URL that matches the network you’re targeting:
  • Naga Dev
  • Naga Test
  • Naga Mainnet
  • Auth Service URL
https://naga-dev-auth-service.getlit.dev
  • Login Server
https://login.litgateway.com
  • Usage: Use Lit’s hosted endpoints while you prototype. Configure your SDK or environment variables with these URLs.
The hosted services are best suited for prototyping. Self-host the Auth Service and Login Server for production traffic or when you need custom configuration.

​
Payment Delegation APIs

The Auth Service also exposes lightweight endpoints that sponsor user requests on the network. These are the same APIs the Lit SDK calls when you use litClient.authService.registerPayer / delegateUsers from the Payment Manager guide.
  • POST /register-payer
    • Headers: x-api-key.
    • Behaviour: generates a random payerSecretKey, hashes it with the API key, and derives a child wallet from LIT_DELEGATION_ROOT_MNEMONIC.
    • Response: { success, payerWalletAddress, payerSecretKey }. The service does not persist the secret—you must store it securely (KMS, vault, etc.).
    • Rotation: call the endpoint again with the same API key to rotate the secret and derive a new child wallet.
  • POST /add-users
    • Headers: x-api-key, payer-secret-key; body is a JSON array of user addresses.
    • Behaviour: recomputes the same child wallet on the fly and calls PaymentManager.delegatePaymentsBatch so the payer sponsors those users.
Running the Auth Service yourself keeps the derivation mnemonic and payer secrets inside your infrastructure. The Lit-hosted instance is great for quick starts, but you remain responsible for storing the returned payerSecretKey.
If you prefer not to run an Auth Service at all, you can still sponsor users manually: create a payer wallet, fund it, and call paymentManager.delegatePayments* directly from your backend. See Payment Manager Setup for sample code.

​
Install the SDK

Run the following command to install the SDK: 
npm i @lit-protocol/auth-services

​
Lit Auth Service

Choose how to run:
  • One-click Deploy (Railway)
  • Container image (Docker)
  • Use the package (Node.js)

​
One-click Deploy (Railway)

Deploy on Railway

​
Container image

docker run \
  -p 6380:6380 \
  --env-file .env \
  ghcr.io/lit-protocol/lit-auth-server:latest

​
Use the package (Node.js)

1

Create the Lit Auth Service

Create the Lit Auth Service instance.
// Auth Server Setup
import { createLitAuthServer } from "@lit-protocol/auth-services";

const litAuthServer = createLitAuthServer({
  port: process.env.PORT || 6380,
  network: process.env.NETWORK || "naga-dev",
  litTxsenderRpcUrl: process.env['LIT_TXSENDER_RPC_URL'],
  litTxsenderPrivateKey: process.env['LIT_TXSENDER_PRIVATE_KEY'],
  litDelegationRootMnemonic: process.env['LIT_DELEGATION_ROOT_MNEMONIC'],
  enableApiKeyGate: process.env['ENABLE_API_KEY_GATE'] === "true",
});

// Start the auth server
await litAuthServer.start();
2

Start the background worker

// Worker Setup
import { startAuthServiceWorker } from "@lit-protocol/auth-services";

// Start the background worker for processing PKP minting operations
await startAuthServiceWorker();

// The worker handles:
// - Background PKP minting operations (non-blocking)
// - Job queue processing with BullMQ
// - Redis connection management
// - Error handling and retry logic for minting jobs
3

Setup environment variables

Setup the environment variables.
# Network configuration (supports naga-dev, naga-test, naga)
NETWORK=naga-dev
LOG_LEVEL=debug

# Lit transaction sender settings
LIT_TXSENDER_RPC_URL=https://yellowstone-rpc.litprotocol.com
LIT_TXSENDER_PRIVATE_KEY=your_private_key
LIT_DELEGATION_ROOT_MNEMONIC=

# Redis settings for job queue and caching
REDIS_URL=redis://user:pass@redis-host.com:12345
PORT=6380

# Rate limiting configuration
ENABLE_API_KEY_GATE=true
MAX_REQUESTS_PER_WINDOW=10
WINDOW_MS=10000

# Stytch configuration (for OTP services)
STYTCH_PUBLIC_TOKEN=your_stytch_public_token
STYTCH_SECRET=your_stytch_secret

​
Lit Login Server

​
Prerequisites

You should set the callback/redirect URLs to the same domain as the Login Server e.g.

​
One-click Deploy (Railway)

Deploy on Railway

​
Container image

docker run \
  -p 3300:3300 \
  -e GOOGLE_CLIENT_ID=your_google_client_id \
  -e GOOGLE_CLIENT_SECRET=your_google_client_secret \
  -e DISCORD_CLIENT_ID=your_discord_client_id \
  -e DISCORD_CLIENT_SECRET=your_discord_client_secret \
  ghcr.io/lit-protocol/lit-login-server:latest

​
Use the package (Node.js)

1

Create the Lit Login Server

Create the Lit Login Server instance.
// Login Server Setup  
import { createLitLoginServer } from "@lit-protocol/auth-services";

const litLoginServer = createLitLoginServer({
  port: 3300,
  host: "0.0.0.0",
  stateExpirySeconds: 30,

  // OAuth provider configuration
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
    discord: {
      clientId: process.env.DISCORD_CLIENT_ID!,
      clientSecret: process.env.DISCORD_CLIENT_SECRET!,
    },
  },
});

// Start the login server
await litLoginServer.start();
2

Setup environment variables

# OAuth provider credentials

# Google
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Discord
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
When you run a custom Login Server, the DISCORD_CLIENT_ID is embedded into the authMethodId that Lit nodes use to locate the correct PKP. Make sure the value matches the client ID you used when minting the Discord auth method.