Managed End-User Auth

Let the platform handle sign-in for your app's users. You set an access policy; the platform serves the login/signup pages, stores the accounts and sessions, and blocks unauthenticated visitors at the edge — they never reach your app, so bots and anonymous traffic don't consume its resources or wake it up.

This is for the end-users of your app (the people who visit it), not for your onvibe account. Don't build your own login tables for the common case — use this.

Set the policy

The policy is configuration: it lives in onvibe.json, alongside the allowlist and the public paths. Change it with the config cycle — get_config → edit → deploy (see onvibe://docs/config):

{
  "version": "<keep as downloaded>",
  "access": { "policy": "signup" }
}

Password mode is the one exception, because the password is a secret and secrets never go in the config file: set it with set_access_policy({ project_id, policy: "password", password: "..." }) — the only tool that still writes access config. Visitors enter the shared password at /auth/login and are let in; there are no accounts and no currentUser() identity. Changing the password signs everyone out.

For allowlist, the authorized emails are part of the same file — the list is complete, so deploying it also revokes anyone you removed:

{
  "version": "<keep as downloaded>",
  "access": { "policy": "allowlist", "allowlist": ["ana@example.com", "bo@example.com"] }
}

The login pages are automatic

When the policy is signup or allowlist, the platform serves sign-in and registration at /auth/login (and /auth/signup, /auth/logout). You do not route these paths — the platform intercepts exactly those three, before the request reaches your app. Everything else (including other /auth/* paths like /auth/profile) goes to your app as normal. This reservation applies only while the app has a policy other than public: a public app can use /auth/login for its own route freely. So: if you enable managed auth, don't build your own /auth/login, /auth/signup or /auth/logout.

An unauthenticated request is redirected to the login page without ever hitting your app. That's the whole point: no wasted resources on traffic that isn't allowed in.

Branding: logo + title

The login, signup, password and reset pages show your app's logo and title, so they look like part of your app rather than a generic gate:

• Logo — set it with set_logo (a full icon set is generated). Until you do, the pages show a neutral default (the app initial on a colored tile). The logo is served by the platform, so it never wakes your app.
• Title — the app's display name, set via title in onvibe.json (download → edit → redeploy; see the config doc). If you don't set one, it defaults to the subdomain (the project id).

Read the signed-in user

The platform injects the identity as signed request headers. Use currentUser() from ./.onvibe/helpers.ts, which verifies the signature for you (a request that didn't come through the platform gate is rejected):

import { currentUser } from "./.onvibe/helpers.ts";

export default async function handler(req: Request): Promise<Response> {
  const user = await currentUser(req);   // { id, email } | null
  if (!user) return new Response("Unauthorized", { status: 401 });

  // user.id is a stable, immutable key — use it (not the email) to key this
  // person's rows in your database.
  return new Response(`Hello ${user.email}`);
}

currentUser() returns null for anonymous requests, for cron triggers, and for any request whose identity header isn't validly signed. Never trust a raw X-Onvibe-User header yourself — always go through currentUser().

Note: under a plain signup/allowlist policy the gate is all-or-nothing — anonymous visitors are redirected to login before your handler runs, so currentUser() is never null and the 401 branch above is effectively dead. It becomes reachable only on public paths (below), where anonymous visitors are allowed through.

Mixed public + private apps (public paths)

Many apps need a mix: a creator signs in to CREATE something, but anonymous visitors PARTICIPATE via a shared link (Doodle, RSVP, public polls, feedback boards). Keep the app on a signup or allowlist policy and open just the visitor-facing routes:

{
  "version": "<keep as downloaded>",
  "access": { "policy": "signup", "publicPaths": ["/", "/d/*", "/api/*/vote"] }
}

• Patterns: exact (/vote), subtree (/d/* = /d and everything under it), or per-segment glob (/api/*/vote, where * does not cross /). Omit the field (or use []) to clear it — back to all-or-nothing.
• On a public path the edge does not block anonymous visitors — so currentUser() can return null there; branch on it (show a read-only/participate view vs. a full one). If the visitor does have a session, their identity is still injected, so currentUser() works too.
• Every route not listed still follows the policy and is blocked at the edge. Bots hitting private routes still never wake the app.
• Trade-off: serving a public route does wake the app (it has to render it). The resource saving is only on unauthorized hits to the gated routes — not on anonymous public traffic.
• Only meaningful when the policy isn't public. Keep the list tight: a pattern that's too broad (e.g. /*) makes the whole app public.

Manage accounts

list_app_users({ project_id })              // email + signup date (never passwords)
create_app_user({ project_id, email, password? })   // create an account directly
update_app_user({ project_id, email, new_email?, password? })  // rename / reset password
remove_app_user({ project_id, email })      // deletes the account and signs it out everywhere
create_password_reset({ project_id, email })  // one-time reset link to share (valid 7 days)

Importing users from another auth system

To migrate an existing user base into managed auth:

• If the old system used bcrypt, import the hashes directly so people keep their passwords:

  import_app_users({ project_id, users: [{ email, password_hash: "$2b$..." }, ...] })
  

  (create_app_user also takes password_hash for a single account.) Max 500 per call.
• If the old hashes are NOT bcrypt (PBKDF2, argon2, scrypt, …), you can't reuse them. Import the emails without a password — each account comes back with a one-time reset_url:

  import_app_users({ project_id, users: [{ email }, ...] })   // → results[].reset_url
  

  Share each reset_url with its user (valid 7 days); they open it, set a password, and are signed in. You can also mint one later with create_password_reset.
• A common flow: read the old users straight from the app's database with query_sql, then feed them to import_app_users.

Self-service "forgot password": when the platform's system email is configured, the login page shows a Forgot password? link — the user enters their email and gets a reset link by email, no action needed from you. You can still mint links yourself with create_password_reset (e.g. for imports, or if email isn't configured).

Notes

• Changing the policy takes effect as soon as the onvibe.json is deployed. Switching a public app to signup will send existing deep links to the login page.
• Cron/scheduled tasks are unaffected. The gate only applies to public web traffic; scheduled triggers reach your app directly, so a job keeps running with any policy. A cron request has no end-user, so currentUser() returns null for it (guard cron paths with isCronRequest).
• Order of checks: a paused app or one whose owner has no active subscription shows its own page (paused / subscription-required) even to signed-in users — those are checked before the auth gate, so you won't see a login page for an app that isn't serving anyway.
• With allowlist, removing an email from the file (and deploying) stops future logins; call remove_app_user too to close its current sessions right away.
• Sessions last 30 days. Passwords are stored hashed; the platform never exposes them.
• Managed vs. self-managed: this mode keeps auth out of your app entirely. If you truly need custom profile fields or your own flows you can build auth inside the app instead — but don't run both on the same app, and prefer managed for anything standard.