How-to guide

Create the first admin

On first run Workbench is unconfigured. Creating the first administrator is the one bootstrap step that must happen before anything else. The endpoint refuses a second call once an admin exists, so it is safe to expose during setup.

Option A — from the browser (recommended)

Open Workbench (http://127.0.0.1:8080 for the quickstart). A fresh install with no admin renders an admin-creation form. Submit an email, display name, and a strong password — you are logged in and the rest of setup continues in the UI.

Option B — via the API (automation)

Check the bootstrap state, create the admin, then log in to a cookie jar:

WORKBENCH=http://127.0.0.1:8080

# A fresh install returns {"bootstrap_required": true}
curl -fsS "$WORKBENCH/api/setup/status"

# Create the first admin (201 Created).
curl -fsS -X POST "$WORKBENCH/api/setup/admin" \
  -H 'Content-Type: application/json' \
  -d '{
        "email": "you@example.com",
        "display_name": "First admin",
        "password": "<a-strong-password>"
      }'

# Log in; keep the cookie jar for license activation and later steps.
curl -fsS -X POST "$WORKBENCH/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"<the-password-you-chose>"}' \
  -c /tmp/wb.cookies

Verify it is locked

curl -fsS "$WORKBENCH/api/setup/status"
# {"bootstrap_required": false}

A second POST /api/setup/admin now returns 409 Conflict. That is intentional and is the safe state.

Choose a password that does not contain the word password and that exceeds the configured minimum length — the rejection response names the rule that failed. Add further operators (admin / editor / viewer) or wire up SSO afterwards.

Next, activate your license.