Email and password

The classic method. A person gives an email and chooses a password; later they sign in with both. It works everywhere and needs no extra setup, and you can add codes, links, social and passkeys alongside it.

Sign-in and registration page — Users & auth → Sign-in & registration: ways to sign in, identifiers and registration.

In Studio

Users & auth → Sign-in → Sign-in & registration. The Registration card:

Setting	Meaning	Key
Self-registration	Anyone may create an account. Turn it off to create people yourself or by invitation	`signup_enabled`
Verify email before sign-in	A new account must open the link in its confirmation email first	`require_email_verification`
Sign-up form layout	Two steps puts the account on the first screen and the rest on the second. Auto does that when more than two details are asked	`signup_form.steps`

How strong a password must be is on its own page: Password policy.

const { user, session, verificationRequired } = await pawabase.auth.signUp({
  email: "ada@example.com",
  password: "a long passphrase",
  name: "Ada",
  username: "ada",
  data: { plan: "free" },                       // stored in user_metadata
  redirectTo: "https://myapp.com/welcome",     // where the confirmation link sends them
});

result = pb.auth.sign_up(
    email="ada@example.com",
    password="a long passphrase",
    name="Ada",
    username="ada",
    data={"plan": "free"},
    redirect_to="https://myapp.com/welcome",
    accepted_terms=True,
)
result.user, result.session, result.verification_required

Two outcomes:

Signed in at once. session is set and the client stores it.
Confirmation first. verificationRequired is true and session is null. Show “check your inbox”. When they click the link they land on redirectTo, signed in. See Email verification.

Whether the second outcome happens depends on Verify email before sign-in. The redirectTo address must be on your redirect list. Extra details your sign-up form collects (company, birthday, terms) go in data and are checked by the rules you set under Attributes.

const result = await pawabase.auth.signInWithPassword({ email, password });

if (result.status === "mfa_required") {
  const session = await result.verify(codeFromUser);   // finish the second step
}

result = pb.auth.sign_in_with_password(email=email, password=password, remember_device=True)

if result.status == "mfa_required":
    session = result.verify(code_from_user)

If the account has two-step verification, the call does not finish; it returns mfa_required with a verify function. To sign in scoped to an organization, add org: "acme".

Errors to handle

A wrong password and an unknown email give the same AuthenticationError, on purpose, so nobody can find out which addresses have accounts.

import { AuthenticationError, PermissionError, ValidationError, RateLimitError, ConflictError } from "@pawabase/client";

try {
  await pawabase.auth.signInWithPassword({ email, password });
} catch (e) {
  if (e instanceof AuthenticationError) setMessage("Wrong email or password.");
  else if (e instanceof PermissionError) setMessage("This account can't sign in right now.");   // disabled or locked
  else if (e instanceof ValidationError) setMessage(e.fieldError("email") ?? "Check your details.");
  else if (e instanceof RateLimitError) setMessage("Too many tries. Wait a moment.");
  else throw e;
}

from pawabase import AuthenticationError, ForbiddenError, ValidationError, RateLimitedError

try:
    pb.auth.sign_in_with_password(email=email, password=password)
except AuthenticationError:
    message = "Wrong email or password."
except ForbiddenError:
    message = "This account can't sign in right now."
except ValidationError:
    message = "Check your details."
except RateLimitedError:
    message = "Too many tries. Wait a moment."

On sign-up, an address already in use is a ConflictError, a password that fails the policy is a ValidationError on the password field, and an email domain you have blocked is refused too (restrictions). After repeated failures the account locks for a while: see Attack protection. Sign-up and sign-in share a rate limit, so never retry in a loop.

A complete form

function SignUp() {
  const [fields, setFields] = useState({ email: "", password: "" });
  const [errors, setErrors] = useState<Record<string, string[]>>({});
  const [sent, setSent] = useState(false);

  async function submit(e: React.FormEvent) {
    e.preventDefault();
    setErrors({});
    try {
      const { verificationRequired } = await pawabase.auth.signUp({
        ...fields,
        redirectTo: `${location.origin}/welcome`,
      });
      setSent(verificationRequired);               // otherwise onAuthStateChange signs them in
    } catch (err) {
      if (err instanceof ValidationError) setErrors(err.byField());
      else if (err instanceof ConflictError) setErrors({ email: ["That address already has an account."] });
      else throw err;
    }
  }

  if (sent) return <p>Check your inbox to confirm your email.</p>;
  return (
    <form onSubmit={submit}>
      <input type="email" autoComplete="email" onChange={(e) => setFields({ ...fields, email: e.target.value })} />
      {errors.email?.map((m) => <p key={m}>{m}</p>)}
      <input type="password" autoComplete="new-password" onChange={(e) => setFields({ ...fields, password: e.target.value })} />
      {errors.password?.map((m) => <p key={m}>{m}</p>)}
      <button>Create account</button>
    </form>
  );
}

Create users yourself

With self-registration off, create people from the dashboard (Users → New user) . Leave the password empty to have the person set one through a recovery link.

Good practice

Set autocomplete="email", "current-password" and "new-password" so password managers work, and allow paste.
Prefer a long minimum length to complicated character rules.
Offer a second way in (passkeys, codes). Fewer passwords means fewer resets.
Never log passwords. Never email them.

Password policy

Set the rules.

Account recovery

Forgotten passwords.

Getting started

Sign-in methods

Sign-up

Security

People

Developers

Email and password

In Studio

Errors to handle

A complete form

Create users yourself

Good practice

Password policy

Account recovery

​In Studio

​Sign up

​Sign in

​Errors to handle

​A complete form

​Create users yourself

​Good practice

Password policy

Account recovery

In Studio

Sign up

Sign in

Errors to handle

A complete form

Create users yourself

Good practice