# /zibby-set-auth — set, rotate, or disable auth on a Zibby Managed App You are helping the user put auth in front of their app's public URL — or rotate / remove it. Canonical docs: **https://docs.zibby.app/apps/auth** ## Why this matters Every Managed App gets a public `https://.apps.zibby.app` URL. Without auth, ANYONE with the URL can hit the app. For tools like n8n / Grafana / Outline that's a real risk — the URL is guessable from the catalog. Zibby fronts the app with an **auth sidecar** that supports two modes: | Mode | What it does | When to use | |---|---|---| | `basic` | HTTP Basic auth (browser prompt) | Quick personal tools, dashboards you visit yourself | | `token` | `Authorization: Bearer ` header | API-only apps, scripted callers, webhook receivers | | `none` | No auth (raw app) | Apps with their own auth (n8n has built-in login) — `--off` to disable | ## Three operations ### 1. Set auth (first time) ``` Bash(zibby app set-auth --auth-type basic --auth-user admin --auth-password $(openssl rand -hex 16)) Bash(zibby app set-auth --auth-type token --auth-token $(openssl rand -hex 32)) ``` The auth sidecar updates within ~5s. No app-container restart. ### 2. Rotate (change password / token) Same command shape as set. Old credentials stop working immediately when the auth-layer reload completes. ``` Bash(zibby app set-auth --auth-type basic --auth-user admin --auth-password $(openssl rand -hex 16)) Bash(zibby app set-auth --auth-type token --auth-token $(openssl rand -hex 32)) ``` ### 3. Disable (remove auth — go raw) ``` Bash(zibby app set-auth --off) ``` `--off` short-circuits to `authType=none`. The auth sidecar is removed; the app's URL exposes the app directly. Only safe if the app has its own login (e.g. n8n, wordpress, grafana with `GF_AUTH_*` configured). ## Steps 1. **Identify the instanceId.** `Bash(zibby app list)` if user only has the friendly name. 2. **Find the current state:** ``` Bash(zibby app status ) ``` Look at `authType`. If it's already what they want, skip the change. 3. **Decide which mode.** Ask the user: - "Will you hit this from a browser (basic) or only from scripts / webhooks (token)?" - If the answer is "it has its own login" → `--off`, and confirm they trust the app's built-in auth. 4. **Generate credentials securely.** For passwords / tokens, use `openssl rand -hex 16` (basic) / `openssl rand -hex 32` (token). NEVER reuse a password the user typed in chat — credentials in chat history leak. 5. **Run the command.** ALWAYS pass credentials via env / `$(…)` substitution rather than as literal strings in the command. The CLI also accepts `ZIBBY_APP_AUTH_PASSWORD` / `ZIBBY_APP_AUTH_TOKEN` env vars if the user prefers. 6. **Show the user the credentials ONCE.** The CLI prints them on success. Tell the user to save them — they're not recoverable from the backend (only re-rotateable). 7. **Verify auth is on:** ``` Bash(curl -i https://.apps.zibby.app/) # should be 401 with basic, 401 with token Bash(curl -i -u admin: https://.apps.zibby.app/) # should be 200 Bash(curl -i -H "Authorization: Bearer " https://.apps.zibby.app/) # 200 ``` ## When NOT to rotate - App is being used live — rotation invalidates old creds immediately, mid-session. Coordinate with the user. - You don't have a place to put the new creds — losing track of a freshly rotated token locks you out of your own app. Save first. ## Common pitfalls - **`--auth-user` must be a single ASCII printable token, 1-64 chars.** Spaces, unicode, control chars all 400. - **Forgetting to confirm `--off`** on an app without its own auth → public URL exposed. The CLI will let you do it. The user might regret it. - **Bearer-token mode + app has its own login** → users see a confusing 401 from the auth layer before the app login page shows. Pick one auth layer, not two. - **Reloading the auth layer mid-request** can briefly 502 inflight responses. Set / rotate during a quiet window if the app is high-traffic.