Config Options

Every MarzbanSDK configuration field — `baseUrl`, auth, `timeout`, `retries`, logger and webhook secret — with defaults and Zod validation rules.

The object is passed to createMarzbanSDK or the MarzbanSDK constructor. All fields are validated by Zod before the SDK boots — invalid config throws a immediately.

Reference

Field	Type	Required	Default	Description
`baseUrl`	`string`	Yes	—	Base URL of the Marzban instance. Must be a valid URL with protocol. Example: `https://vpn.example.com`
`username`	`string`	Yes	—	Admin username for authentication (non-empty).
`password`	`string`	Yes	—	Admin password for authentication (non-empty).
`token`	`string`	No	—	Existing JWT token. If provided, the SDK uses it directly instead of calling the login endpoint.
`authenticateOnInit`	`boolean`	No	`true`	When `true`, `createMarzbanSDK` calls `authorize()` before returning. Set to `false` for deferred or manual auth.
`timeout`	`number`	No	`30000`	HTTP request timeout in milliseconds. Pass `0` to disable (wait forever).
`retries`	`number`	No	`3`	Number of automatic retries for failed HTTP requests. Uses exponential backoff. WebSocket log streams don't use this — see `reconnect` below.
`logger`	`false \| \|`	No	env-aware	Controls the SDK's internal logging. `false` disables it entirely; a object configures the built-in console logger (level, timestamps); pass your own implementation (e.g. Winston, Pino) to route SDK logs through it instead. Left unset, the level defaults to `info` in development and `error` in production. Full reference: Logging.
`webhook`	`{ secret?: string }`	No	—	Webhook configuration. Set `secret` to enable HMAC-SHA256 signature verification.
`httpAgent`		No	—	Node.js `http.Agent` (or compatible) used for `http:` requests. Ignored in browsers.
`httpsAgent`		No	—	Node.js `https.Agent` (or compatible) used for `https:` requests and the WebSocket log stream. Ignored in browsers. See Self-signed certificates below.
`reconnect`		No	enabled	Auto-reconnects a dropped `sdk.logs` WebSocket stream: exponential backoff, bounded by a 10-minute time budget by default. `false` disables reconnecting entirely; `true` enables it with defaults; pass an object to tune the backoff, budget, or attempt count. This is the SDK-wide default — a `logs.connect*()` call's own `reconnect` option overrides it. Full reference: Reconnect & Stream Lifecycle.

Minimal config

import { createMarzbanSDK } from 'marzban-sdk'

const sdk = await createMarzbanSDK({
  baseUrl: 'https://vpn.example.com',
  username: 'admin',
  password: 'secret',
})

Full config example

import { createMarzbanSDK } from 'marzban-sdk'

const sdk = await createMarzbanSDK({
  baseUrl: 'https://vpn.example.com',
  username: 'admin',
  password: 'secret',
  timeout: 15_000,        // 15 seconds
  retries: 5,
  authenticateOnInit: true,
  logger: {
    level: 'debug',
    timestamp: true,
  },
  webhook: {
    secret: process.env.MARZBAN_WEBHOOK_SECRET,
  },
})

Supply an existing token

If you manage JWT tokens yourself, skip the login step by providing the token field:

const sdk = await createMarzbanSDK({
  baseUrl: 'https://vpn.example.com',
  username: 'admin',
  password: 'secret',
  token: 'eyJhbGciOi...', // already-obtained JWT
  authenticateOnInit: false,
})

If the supplied token expires, the SDK will re-authenticate using username and password automatically. Both fields are still required.

Self-signed certificates & custom CA

Self-hosted Marzban panels are frequently served behind a self-signed or internal-CA certificate. Rather than disabling TLS verification, pass a Node https.Agent configured with the CA to trust:

import { readFileSync } from 'node:fs'
import https from 'node:https'
import { createMarzbanSDK } from 'marzban-sdk'

const sdk = await createMarzbanSDK({
  baseUrl: 'https://panel.example.com',
  username: 'admin',
  password: 'secret',
  httpsAgent: new https.Agent({ ca: readFileSync('ca.pem') }),
})

The same httpsAgent also covers sdk.logs — see WebSocket Logs. httpAgent/httpsAgent are Node-only: they're ignored (with a warning) in the browser, where there's no way to hand a custom CA to the native fetch/WebSocket implementations.

Don't set rejectUnauthorized: false on the agent to work around a certificate error — that disables verification entirely, for every connection the agent makes, not just the one you're debugging. Trust the specific CA instead, as shown above.

Retry behaviour

When retries > 0, failed HTTP requests are retried with exponential backoff:

Attempt	Delay
1	1 s
2	2 s
3	4 s
…	… (capped at 30 s)

Only safe methods (GET, HEAD, OPTIONS) are retried — see HTTP & Retry for the full method/status breakdown.

WebSocket log streams don't use retries — they have their own reconnect policy (backoff + a time budget instead of an attempt count). See Reconnect & Stream Lifecycle.

Set retries: 0 to disable automatic HTTP retries.

Validation errors

If you pass an invalid config (e.g. missing baseUrl, non-integer timeout), the SDK throws a before any network call is made:

import { isConfigurationError } from 'marzban-sdk'

try {
  const sdk = await createMarzbanSDK({ baseUrl: '', username: '', password: '' })
} catch (err) {
  if (isConfigurationError(err)) {
    console.error(err.message) // "Invalid SDK configuration"
    console.error(err.details) // Zod validation issues
  }
}