Skip to content

Config

Manage server configuration.

Get Config

Get the current server configuration.

Endpoint

GET /api/config

Example Request

curl -H "Authorization: Bearer your-token" \
  http://localhost:3100/api/config

Success Response

{
  "mode": "local",
  "server": {
    "host": "127.0.0.1",
    "port": 3100
  },
  "publicUrl": "",
  "email": {
    "enabled": false
  },
  "logLevel": "info"
}

Update Config

Update server configuration.

Endpoint

POST /api/config

Request Body

{
  mode?: 'local' | 'live'           // Optional
  server?: {                        // Optional
    host?: string
    port?: number
  }
  publicUrl?: string                // Optional
  email?: {                         // Optional
    enabled?: boolean
    provider?: string               // e.g. 'smtp', 'sendgrid', 'mailgun', 'resend', 'ses', 'manual'
    options?: Record<string, Record<string, unknown>>
    fromByProvider?: Record<string, string>
  }
  logLevel?: string                 // Optional
}

Example Request

curl -X POST http://localhost:3100/api/config \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "local",
    "server": {
      "host": "0.0.0.0",
      "port": 3100
    },
    "publicUrl": "https://ziri.example.com",
    "email": {
      "enabled": true,
      "provider": "smtp",
      "options": {
        "smtp": {
          "host": "smtp.example.com",
          "port": 587,
          "secure": false,
          "auth": {
            "user": "user@example.com",
            "pass": "password"
          }
        }
      },
      "fromByProvider": {
        "smtp": "noreply@example.com"
      }
    }
  }'

Success Response

{
	"success": true,
	"message": "Configuration saved successfully. Restart the proxy server for server settings to take effect.",
	"config": {
		"mode": "local",
		"server": {
			"host": "0.0.0.0",
			"port": 3100
		},
		"publicUrl": "https://ziri.example.com",
		"email": {
			"enabled": true,
			"provider": "smtp"
		},
		"logLevel": "info"
	}
}

Note: Server settings (host, port) require a restart to take effect.

Configuration Fields

Mode

  • local - Local mode (default)

Server

  • host - Server host (default: 127.0.0.1, Docker: 0.0.0.0)
  • port - Server port (default: 3100)

Public URL

The public URL where users can access ZIRI. Used in email notifications and API responses.

Email

Email configuration for sending user credentials and password resets.

Use provider to select the active email provider and set provider-specific values in options[provider]. Set sender addresses in fromByProvider[provider].

Example (SMTP):

{
	"enabled": true,
	"provider": "smtp",
	"options": {
		"smtp": {
			"host": "smtp.example.com",
			"port": 587,
			"secure": false,
			"auth": {
				"user": "user@example.com",
				"pass": "password"
			}
		}
	},
	"fromByProvider": {
		"smtp": "noreply@example.com"
	}
}

List Email Providers

Get available email providers and their dynamic config fields.

Endpoint

GET /api/config/email-providers

Success Response

{
	"providers": [
		{
			"id": "smtp",
			"label": "SMTP",
			"fields": [
				{ "key": "host", "label": "Host", "type": "text", "required": true }
			],
			"fromRequired": true
		}
	]
}

Provider IDs and field definitions are generated by the backend provider registry.

Supported Email Providers

  • smtp
  • sendgrid
  • mailgun
  • resend
  • ses
  • manual

Log Level

Logging level: debug, info, warn, error.

Configuration Precedence

Configuration is loaded in this order:

  1. Environment variables (PORT, HOST, CONFIG_DIR, ZIRI_ROOT_KEY, ZIRI_ENCRYPTION_KEY)
  2. Config file (config.json)
  3. Defaults

Environment variables override config file settings. Secrets like the root key are never returned by this API; they are stored only in .ziri-root-key (or provided via ZIRI_ROOT_KEY).

Config File Location

  • Windows: %APPDATA%\ziri\config.json
  • macOS/Linux: ~/.ziri/config.json
  • Docker: /data/config.json (when CONFIG_DIR=/data)

Next Steps