Guides

User Authentication

Implement user sign-in and session management in your app using MUDBASE Auth.

This is about authenticating your app's end-users — the people who use the product you're building. That's separate from the API key your backend uses to call MUDBASE; see Authentication (Concepts) for how the two relate.

Enable local authentication

In Console → Authentication, enable the local provider for your project. New users register with an email and password, scoped to your project — the same email can exist as a separate user in a different project.

Register a user

const res = await fetch("https://api.mudbase.dev/api/auth/local/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    projectId: "YOUR_PROJECT_ID",
    email: "user@example.com",
    password: "a-strong-password",
    firstName: "Ada",
    lastName: "Lovelace",
  }),
});
const data = await res.json();

const res = await fetch("https://api.mudbase.dev/api/auth/local/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    projectId: "YOUR_PROJECT_ID",
    email: "user@example.com",
    password: "a-strong-password",
    firstName: "Ada",
    lastName: "Lovelace",
  }),
});
const data = await res.json();

Registration sends a verification email automatically. Whether an unverified user can sign in depends on your project's requireEmailVerification setting — see Projects.

Sign in

const res = await fetch("https://api.mudbase.dev/api/auth/local/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com", password: "a-strong-password" }),
});
const { token, refreshToken, expiresIn, user } = await res.json();

const res = await fetch("https://api.mudbase.dev/api/auth/local/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com", password: "a-strong-password" }),
});
const { token, refreshToken, expiresIn, user } = await res.json();

token is a short-lived JWT (expiresIn is in seconds — 24 hours by default). Store it and send it as Authorization: Bearer <token> on requests you make on behalf of that user. Store refreshToken to get a new token once it expires, without asking the user to sign in again.

Password reset

POST /api/auth/local/password-reset sends a reset email for a given project + email. The user completes it with POST /api/auth/local/password-reset/confirm (OTP-based) or POST /api/auth/local/password-reset/:token (link-based), depending on how your project is configured.

Checking the current session

GET /api/auth/session with the user's Bearer token returns the current user, or 401 if the token is invalid, expired, or was revoked (e.g. by a password change or explicit logout).

See Error Handling for how to react to a 401 by refreshing the token instead of immediately signing the user out.