Admin Password

By default, the Admin UI and Admin API are open — anyone who can reach port 8081 can view and modify your entire configuration. Setting an admin password adds authentication to all admin endpoints.

Enabling authentication #

Add adminPassword to the server section of your config.yaml:

server:
  host: 0.0.0.0
  port: 8080
  adminPort: 8081
  adminPassword: ${MAGEC_ADMIN_PASSWORD}

Then set the environment variable before starting Magec:

export MAGEC_ADMIN_PASSWORD="your-strong-password"
magec --config config.yaml

When the password is set, every request to /api/ endpoints requires a Authorization: Bearer <password> header. The Admin UI handles this automatically — it shows a login screen on first load and sends the header on every subsequent request.

How it works #

Aspect	Detail
Header	`Authorization: Bearer <password>` on all `/api/` requests
Comparison	Constant-time (`crypto/subtle`) — immune to timing attacks
Rate limiting	5 failed attempts per minute per IP address
Static files	The Admin UI itself (HTML, CSS, JS) is always accessible — only API calls require auth
CORS preflight	`OPTIONS` requests bypass authentication
Auth check	`GET /api/v1/admin/auth/check` — returns `200` if the password is correct, `401` otherwise

When authentication is enabled, the Admin UI shows a password prompt before anything else:

The password is stored in memory only — closing the browser tab requires re-authentication
No cookies, no localStorage, no session tokens
The UI calls /api/v1/admin/auth/check on load to determine if authentication is needed

Docker and Kubernetes #

Pass the password as an environment variable — never hardcode it in config.yaml:

Docker Compose #

services:
  magec:
    image: ghcr.io/achetronic/magec:latest
    environment:
      MAGEC_ADMIN_PASSWORD: "${MAGEC_ADMIN_PASSWORD}"

Kubernetes #

env:
  - name: MAGEC_ADMIN_PASSWORD
    valueFrom:
      secretKeyRef:
        name: magec-secrets
        key: admin-password

What happens without a password #

If adminPassword is not set (or is empty), the server starts normally with a warning in the logs:

WARN  Admin API is unprotected — set adminPassword in config.yaml

All admin endpoints work without authentication. This is fine for local development but should never be used in production or anywhere the admin port is network-accessible.

Secrets encryption #

The admin password also serves as the encryption key for Secrets. When a password is set, secret values are encrypted at rest using AES-256-GCM with a PBKDF2-derived key. Without a password, secrets are stored in plain text and a warning is logged.

The admin password is a single shared credential — there are no user accounts or roles. If you need network-level isolation, restrict access to the admin port using firewall rules or a reverse proxy.