Skip to content

Nginx Proxy Manager Module API Explanation

The Nginx Proxy Manager (NPM) module monitors proxy hosts configuration and availability.

API Execution Logic

The module locates the service matching the identifier npm. It retrieves the administrative credentials (NPM_EMAIL or NPM_USERNAME and NPM_PASSWORD) to execute session token checks.

Authentication Caching and Token Management

NPM does not support static API token authentication; it requires a JWT bearer token. To avoid requesting a new token on every 5-second dashboard refresh, the module implements an authentication caching mechanism:

  1. Token Retrieval: The helper function getToken checks if a token is already cached in memory and verifies it has not expired.
  2. Login Query: If no token is cached, a POST request is sent to /api/tokens containing the identity and password. Upon success, the retrieved token is cached in memory for 12 hours.

Telemetry Request Execution

Once authenticated, the module queries /api/nginx/proxy-hosts using the Bearer JWT token.

  • Token Expiry Retry: If the request returns an HTTP 401 or 403 status (indicating a revoked or prematurely expired token), the cache is cleared immediately. The module requests a new token and retries the proxy host query once.

Data Parsing

  • Primary Metric: The count of enabled proxy hosts (evaluated via host.enabled === 1 or host.enabled === true).
  • Secondary Metric: The total count of configured proxy hosts.

Caching Strategy

The proxy hosts list is cached for 15 seconds (TTL) with a maximum stale window of 60 seconds.