--- name: vibiz-auth description: Set up and change sign-in for a Vibiz Stack project - email and password, verification, magic links, Google, GitHub or Vercel sign-in, allowed email domains, and the callback URLs to register. Use when a Vibiz project's users need to sign in or its sign-in settings need changing. --- # Vibiz sign-in **Connect first.** Not logged in (a tool answers `unauthorized` with `reason: not_logged_in`, or the CLI says "Not logged in")? Run `npx @vibiz/cli login`: show the person the link it prints and ask them to click Authorize (their account is opened on the way if they have none), then go on. Or connect the remote MCP server, nothing to install: `claude mcp add --transport http vibiz https://app.vibiz.app/mcp` (the client opens the same sign-in on first use). Never ask the person to paste a key into the chat. **Keep the CLI current:** a command named here that your `vibiz` doesn't have (an unknown-command or usage error) means the CLI is out of date, not that Vibiz can't do it: run `npm install -g @vibiz/cli@latest` (or `npx -y @vibiz/cli@latest `) and retry, and refresh these skills with `vibiz skills add --global`. Never tell the person something isn't possible because an old CLI lacks the command. Each project has its own sign-in service (the `auth` resource, which brings the database), with separate users in production and development. The development copy trusts `http://localhost:3000` only. ## Before you start - Project id: `./vibiz.json`. Tools: `vibiz_auth_settings { project_id }` reads the development copy; `update: { … }` changes it and `provider: { id, action: "enable_shared" | "remove" }` turns a provider on or off. Or `vibiz auth … --dev`, or `PATCH /v1/projects//auth/settings?env=development`. - No `auth` resource yet? `vibiz_add_resources { project_id, resources: ["auth"] }` (or `vibiz add auth`). - The development copy exists after `vibiz_dev_env` / `vibiz dev`; before that, settings answer `409 dependency_not_ready`. ## Common tasks - **Google sign-in**: shared keys work with no OAuth app: `vibiz_auth_settings { project_id, provider: { id: "google", action: "enable_shared" } }`, `vibiz auth providers add google --dev`, or `PUT …/auth/providers/google?env=development { "credentials": "shared" }`. Only Google has shared keys. - **GitHub or Vercel**: these need the user's own OAuth app. Read `available_providers[]` from the settings: it has `console_url`, the `callback_url` to register and the steps. The user creates the app and enters the secret themselves (`vibiz auth providers add github --own --client-id ` reads it from `GITHUB_CLIENT_SECRET` or a hidden prompt). Never ask the user to paste a client secret into the chat. - **Magic links**: `update: { magic_link: { enabled: true, expires_in_minutes: 30 } }` (5–1440). - **Email and password**: `update: { email_password: { enabled, require_email_verification, email_verification_method: "otp" | "link", disable_sign_up, auto_sign_in_after_verification } }`; `app_name` (1–256 characters) is the name in sign-in emails. - **Only company emails**: `update: { allowed_email_domains: ["acme.com"] }` or `vibiz auth domains acme.com --dev` (at most 50; `[]` / `none` lets anyone sign up). - **Verification by link** needs the project's own SMTP sender (`email_sender`, set by a person in the console, who enters its password); the shared sender only does one-time codes (`email_verification_method: "otp"`). - **Running on another domain**: add it (`vibiz domains add app.example.com --elsewhere`). An owner's is trusted at once; from an agent key, sign-in trusts it once its TXT record (`trust_record`: `_vibiz.app.example.com` = `vibiz-verify=…`) is in and `vibiz domains verify app.example.com` finds it, or the owner confirms it in the console. ## In the app The `nextjs-saas` template has sign-in wired (`lib/auth/server.ts`, `currentUser()`, `/api/auth/*`). The env carries `VIBIZ_AUTH_BASE_URL`, `VIBIZ_AUTH_COOKIE_SECRET`, `VIBIZ_AUTH_JWKS_URL` and `VIBIZ_AUTH_PROJECT_ID`; get the development values with `vibiz dev` (written to `.env.development.local`, never printed). The people who signed up are on the console's Users page (`/projects//users`). ## Limits and boundaries - Not available yet: session lifetime, email templates, MFA, banning users. Say so instead of inventing a setting. - Production settings and test emails are the owner's: an agent key gets `403 owner_only`. Pass `details.next_step` (or `console_url`) on. Own OAuth client secrets and SMTP passwords are typed by a person (the CLI's hidden prompt or the console), never pasted into the chat. - Errors: `dependency_not_ready` (no `auth` resource, or no development copy yet: `vibiz dev`), `invalid_request` (`details` names the field: shared keys for anything but Google, `link` with the shared sender, out-of-range values). **Console links**: production sign-in is changed at `/projects//sign-in` on the console (`?provider=github` opens that provider). In the settings, `available_providers[].console_url` is the provider's own developer console, not ours. `vibiz_docs console-urls` lists every page and its parameters. ## Not hosted on Vibiz? Sign-in works for an app on any host: `vibiz init --resources auth` (brings the database, no hosting), the app's domain is added with `vibiz domains add app.example.com --elsewhere` so sign-in trusts it (from an agent key, after its TXT record proves it), and the host gets only `VIBIZ_APP_KEY` (the app calls `await vibiz.loadEnv()` from `@vibiz/app` at start for `VIBIZ_AUTH_*`). Each extra domain the app answers on is added the same way. The vibiz-use-one skill has every step. ## References - `references/sign-in.md`: settings, limits, errors. - `references/keys.md`: environments and who may do what.