🌐 Nginx Proxy Manager Plus (NPMplus) SDK

The Premium JavaScript SDK for Programmatic NPMplus Control

Website • Support • Report Bug

📌 Table of Contents

• Overview
• Key Features
• Installation
• Authentication Architecture
  • 1. Automatic Credentials Session Mode
  • 2. Stateless Token-Only Mode
• Quick Start
• Full API Reference Directory
• Advanced Usage Example
• Development & Testing
• Support & Authors
• License

📖 Overview

The NPMplus JS Client is a premium, fully-typed, and modular API wrapper for the Nginx Proxy Manager Plus (NPMplus) admin interface. Written from the ground up to support modern ES Modules, this SDK automates session cookie management (__Host-Http-token), JWT token rotation, and provides complete programmatic controls over your proxy hosts, redirection hosts, forwarding streams, Let's Encrypt certificates, user permissions, and security controls.

✨ Key Features

• 🛡️ Secure Session Handler: Automatically extracts and manages CSRF-signed HTTP tokens (__Host-Http-token) inside cookie headers alongside Bearer JWT headers.
• 🔁 Auto-Token Rotation: Automatically refreshes expired JWT tokens in the background with zero developer intervention.
• 🔒 Self-Signed SSL Override: Fully configurable to allow connections to development servers running self-signed HTTPS certificates.
• ⚡ Ultra-Lightweight & Modular: Endpoints are split into specific categories and imported only when invoked (.call(this) binding).
• 💪 Robust JSDoc Integration: Complete type assistance and method documentation inside your IDE.

📥 Installation

npm install nginx-proxy-menager-plus

🔑 Authentication Architecture

1. Automatic Credentials Session Mode

Great for applications executing admin tasks directly. Provide your login details once, and the SDK handles login, session cookie storage, and token validation dynamically.

import NginxProxyMenagerPlus from 'nginx-proxy-menager-plus';

const client = new NginxProxyMenagerPlus({
  proxyURL: 'https://npm.yourdomain.com:8181',
  email: '[email protected]',
  password: 'securePassword',
  rejectUnauthorized: false // Dev/Staging self-signed certificate bypass
});

2. Stateless Token-Only Mode

Recommended for serverless environments or restricted security microservices where you only pass pre-acquired JWT access tokens.

import NginxProxyMenagerPlus from 'nginx-proxy-menager-plus';

const client = new NginxProxyMenagerPlus({
  proxyURL: 'https://npm.yourdomain.com:8181',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  rejectUnauthorized: false
});

🚀 Quick Start

Retrieve current server host stats in just a few lines:

import NginxProxyMenagerPlus from 'nginx-proxy-menager-plus';

const client = new NginxProxyMenagerPlus({
  proxyURL: 'http://s1.wleci.pl:8181',
  email: '[email protected]',
  password: 'superSecretPassword'
});

try {
  const reports = await client.getHostsReport();
  console.log(`Proxy Hosts configured: ${reports.proxy}`);
} catch (error) {
  console.error('Failed to query statistics:', error.message);
}

🗂️ Full API Reference Directory

🔍 1. Public & Utility Endpoints

• await client.health()
  • Returns health statistics of the NPMplus instance.
• await client.schema()
  • Returns the raw Open API swagger JSON schema.
• await client.versionCheck()
  • Query update check against GitHub releases.

🔑 2. Token & 2FA Management

• await client.createToken(credentials?)
  • Log in and acquire active JWT session tokens.
• await client.refreshToken()
  • Refresh the active JWT session.
• await client.verify2FA(challengeToken, totpCode)
  • Verify verification code challenge during a 2FA-secured login.

🌐 3. Proxy Hosts

• await client.getProxyHosts(expand?)
  • Retrieve all configured Proxy Hosts (expand options: access_lists, owner, certificate).
• await client.createProxyHost(data)
  • Create a new Proxy Host.
• await client.getProxyHost(hostID)
  • Fetch details of a single Proxy Host.
• await client.updateProxyHost(hostID, data)
  • Update Proxy Host settings.
• await client.deleteProxyHost(hostID)
  • Delete a Proxy Host configuration.
• await client.enableProxyHost(hostID)
  • Toggle a Proxy Host online.
• await client.disableProxyHost(hostID)
  • Toggle a Proxy Host offline.

↩️ 4. Redirection Hosts

• await client.getRedirectionHosts(expand?)
  • Retrieve redirection hosts (expand options: owner, certificate).
• await client.createRedirectionHost(data)
  • Create a redirection host configuration.
• await client.getRedirectionHost(hostID)
  • Get a single redirection host.
• await client.updateRedirectionHost(hostID, data)
  • Update redirection configuration.
• await client.deleteRedirectionHost(hostID)
  • Delete a redirection host.
• await client.enableRedirectionHost(hostID)
  • Enable a redirection host.
• await client.disableRedirectionHost(hostID)
  • Disable a redirection host.

🔀 5. Port Forwarding Streams

• await client.getStreams(expand?)
  • Get all TCP/UDP forwarding streams.
• await client.createStream(data)
  • Create a new stream forwarding port.
• await client.getStream(streamID)
  • Get stream settings.
• await client.updateStream(streamID, data)
  • Modify stream details.
• await client.deleteStream(streamID)
  • Delete a forwarding stream.
• await client.enableStream(streamID)
  • Enable a port stream.
• await client.disableStream(streamID)
  • Disable a port stream.

🚫 6. Dead Hosts (404 Error Pages)

• await client.getDeadHosts(expand?)
  • Get all configured 404 Hosts.
• await client.createDeadHost(data)
  • Create a new 404 handler host.
• await client.getDeadHost(hostID)
  • Get 404 host details.
• await client.updateDeadHost(hostID, data)
  • Modify 404 host configuration.
• await client.deleteDeadHost(hostID)
  • Delete a 404 host.
• await client.enableDeadHost(hostID)
  • Enable a 404 host.
• await client.disableDeadHost(hostID)
  • Disable a 404 host.

📜 7. SSL Certificates

• await client.getCertificates(expand?)
  • Fetch all available SSL Certificates.
• await client.createCertificate(data)
  • Order a new Let's Encrypt certificate.
• await client.getDNSProviders()
  • Get the list of supported DNS verification challenge providers.
• await client.validateCustomCertificate(formData)
  • Verify custom SSL files before uploading.
• await client.testHTTPReachability(data)
  • Check if the domains are reachable over port 80.
• await client.getCertificate(certID)
  • Get certificate details.
• await client.deleteCertificate(certID)
  • Delete a certificate.
• await client.downloadCertificate(certID)
  • Download the ZIP archive of the certificate files (returns an ArrayBuffer).
• await client.renewCertificate(certID)
  • Trigger Let's Encrypt manual renewal.
• await client.uploadCustomCertificate(certID, formData)
  • Upload custom certificate files (multipart/form-data).

👥 8. Users & Access Management

• await client.getUsers(expand?)
  • List all system users (expand permissions).
• await client.createUser(data)
  • Create a user account.
• await client.getUser(userID)
  • Fetch a user details.
• await client.updateUser(userID, data)
  • Update user information.
• await client.deleteUser(userID)
  • Delete user account.
• await client.setup2FA(userID)
  • Request 2FA registration secret and QR Code.
• await client.get2FAStatus(userID)
  • Verify if 2FA is active.
• await client.enable2FA(userID, totpCode)
  • Activate 2FA with verification.
• await client.disable2FA(userID, totpCode)
  • Deactivate 2FA.
• await client.regenerateBackupCodes(userID, totpCode)
  • Generate new recovery codes.
• await client.updateUserAuth(userID, data)
  • Update passwords.
• await client.updateUserPermissions(userID, data)
  • Modify granular access rules.
• await client.loginAsUser(userID)
  • Acquire a login session impersonating a user.

⚙️ 9. Settings, Reports & Audit Logs

• await client.getSettings()
  • List all system settings.
• await client.getSetting(settingID)
  • Get a single setting.
• await client.updateSetting(settingID, data)
  • Modify a setting.
• await client.getAuditLogs()
  • Retrieve administrator action history.
• await client.getAuditLogEvent(eventID)
  • Fetch specific audit event details.
• await client.getHostsReport()
  • Retrieve proxy statistics report.

🛠️ Advanced Usage Example

Create a Proxy Host, request a Let's Encrypt SSL certificate, and bind them together programmatically:

import NginxProxyMenagerPlus from 'nginx-proxy-menager-plus';

const client = new NginxProxyMenagerPlus({
  proxyURL: 'https://npm.wleci.pl:8181',
  email: '[email protected]',
  password: 'superSecretPassword',
  rejectUnauthorized: false
});

async function deployApp() {
  const domain = 'demo-app.wleci.pl';

  // 1. Check if domain is HTTP reachable first
  const check = await client.testHTTPReachability({ domains: [domain] });
  if (check[0].status !== "200" && check[0].status !== "404") {
    throw new Error(`Domain ${domain} is not reachable over port 80.`);
  }

  // 2. Order Let's Encrypt SSL Certificate
  console.log('Requesting Let\'s Encrypt SSL...');
  const cert = await client.createCertificate({
    provider: 'letsencrypt',
    domain_names: [domain],
    meta: { dns_challenge: false }
  });

  // 3. Deploy Proxy Host pointing to internal Docker App
  console.log('Deploying Proxy Host...');
  const host = await client.createProxyHost({
    domain_names: [domain],
    forward_scheme: 'http',
    forward_host: 'docker-container-app',
    forward_port: 8080,
    certificate_id: cert.id,
    ssl_forced: true,
    hsts_enabled: true,
    http2_support: true,
    npmplus_http3_support: true,
    allow_websocket_upgrade: true
  });

  console.log(`Success! App deployed to https://${domain} (ID: ${host.id})`);
}

deployApp().catch(console.error);

🧪 Development & Testing

All tests run against a local environment configured via test/data.json.

1. Create a test/data.json at the root:

   {
     "proxyURL": "http://your-instance:8181",
     "email": "[email protected]",
     "password": "yourPassword",
     "token": "optional_pre_acquired_jwt_token",
     "rejectUnauthorized": false
   }

   [!NOTE] You can supply token, apiKey, or api_key in the configuration. If provided, tests will execute using the token directly and bypass credential-based log-ins.

2. Execute tests easily via Node/NPM scripts:

   # Test general server connectivity
   npm run test:health
   
   # Test complete Proxy Hosts CRUD cycle
   npm run test:proxy
   
   # Test SSL Certificate creation and DNS query endpoints
   npm run test:certificates

👥 Support & Authors

This SDK was built and is premium-maintained with ❤️ by wleci.pl.
For technical support, custom deployments, or feature inquiries, reach out at [email protected].

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.