Documentation

How it works

You add isitme to your app, and your pages are protected by passkey authentication. No user accounts, no passwords, no OAuth, no database. When you first visit, you register a passkey and become the owner — everyone else is locked out. Authentication uses your device's biometrics (fingerprint, Face ID) via the WebAuthn standard.

Simplest example

Wrap any component in <IsItMe> and it only renders for authenticated users:

import { IsItMe } from "isitme/react";

<IsItMe>
  <h1>Admin dashboard</h1>
  <p>Secret tools here...</p>
</IsItMe>

// Not you? → shows passkey registration / login
// You?     → renders your content

By default, unauthenticated visitors see a built-in login / registration page. Use fallback={false} to hide content silently instead — great for debug UI, admin tools, or anything you want quick access to but hidden from regular visitors:

<IsItMe fallback={false}>
  <DebugPanel />
  <PerformanceMonitor />
  <FeatureFlagEditor />
</IsItMe>

<main>
  {/* your regular app — always visible */}
</main>

Nothing sensitive — just stuff you want to keep out of the way for visitors and have easy access to yourself. The content only renders after you authenticate with your passkey, and disappears completely for everyone else. If you need to protect server routes and API endpoints too, add the server middleware:

Protecting server routes

There are two layers of auth — data gating (server middleware) and UI gating (React/Vue components):

• Data gating: protectedPaths blocks unauthenticated requests at the server. Use for API routes that return sensitive data. Returns 401 JSON.
• UI gating: <IsItMe> wraps your page component and shows a login/register form until authenticated. The page HTML always loads — auth happens client-side via conditional rendering.

Use protectedPaths for API routes. Don't put page paths there — the middleware would block the HTML before your <IsItMe> component can load. Unprotected routes still get req.isAuthenticated for conditional UI:

// Protect API routes on the server — returns 401 for unauthenticated requests
app.use(isitme({
  protectedPaths: ["/api/admin/"],
  loginPage: false,
}));

app.get("/", (req, res) => {
  // public — req.isAuthenticated is still available
  res.render("home", { isOwner: req.isAuthenticated });
});

protectedPaths secures your data at the server level (API routes return 401). Use <IsItMe> on admin pages for the auth UI — it handles login/register client-side and renders your dashboard only after authentication. All routes still get req.isAuthenticated for conditional server-side rendering.

Deployment modes

Quick Start

Pick your framework and paste the code. Protect entire routes or show parts of the UI only to the owner.

import { IsItMe } from "isitme/react";

export default function App() {
  return (
    <IsItMe>
      <h1>Welcome back!</h1>
      <p>Only you can see this.</p>
    </IsItMe>
  );
}

Server Middleware

The server middleware protects your API routes and serves a built-in login page. Pick your framework.

import express from "express";
import cookieParser from "cookie-parser";
import { isitme } from "isitme/express";

const app = express();
app.use(cookieParser());
app.use(isitme());

app.get("/", (req, res) => {
  res.send(`Hello! Authenticated: ${req.isAuthenticated}`);
});

app.listen(3000);

To use a custom login UI instead of the built-in one, set loginPage: false and use the React components or browser API.

Browser API

Plain JS functions from isitme/browser for building your own auth UI without React or Vue.

import { signin, isItMe, logout } from "isitme/browser";

await signin();                   // register or login — one call
const session = await isItMe();  // silent check — no UI
await logout();                   // end session

Example: conditional signin / dashboard button

A common pattern — show a "Sign in" button to visitors and a "Dashboard" link to the owner. No login page needed.

import { signin, isItMe } from "isitme/browser";

const session = await isItMe();
const btn = document.getElementById("auth-btn");

if (session) {
  btn.textContent = "Dashboard";
  btn.onclick = () => location.href = "/dashboard";
} else {
  btn.textContent = "Sign in";
  btn.onclick = async () => {
    await signin();
    location.href = "/dashboard";
  };
}

Plain HTML (no build tools)

Load isitme/browser from a CDN — no npm, no bundler. The same API as the npm package.

<script type="module">
import { signin, isItMe }
  from "https://esm.sh/isitme/browser";

const session = await isItMe();

if (!session) {
  await signin();  // registers or logs in automatically
}

document.body.innerHTML = "<h1>You're in!</h1>";
</script>

Credentials are stored in the cloud automatically — one owner per domain, zero config.

Error handling

All functions throw IsitmeError with a code property you can switch on. Import it from isitme/browser.

import { signin, IsitmeError } from "isitme/browser";

try {
  await signin();
} catch (err) {
  if (err instanceof IsitmeError) {
    switch (err.code) {
      case "NOT_SETUP":
        console.log("No passkey yet — register first");
        break;
      case "ALREADY_SETUP":
        console.log("Domain already claimed — use login");
        break;
      case "PASSKEY_CANCELLED":
        console.log("User cancelled the prompt");
        break;
      case "NETWORK_ERROR":
        console.log("Could not reach the auth server");
        break;
      default:
        console.log(err.message);
    }
  }
}

Error codes

When to use manual functions

signin() handles everything for most apps. Use the manual functions when you need explicit control:

React Components

Drop-in components from isitme/react for building a custom auth UI. Works with Next.js, Vite, CRA, or any React setup.

import { IsItMe } from "isitme/react";

export default function Page() {
  return (
    <IsItMe>
      <h1>You're in!</h1>
    </IsItMe>
  );
}

import { IsItMe } from "isitme/react";

<IsItMe clientOnly>
  <AdminPanel />
</IsItMe>

"use client";
import { useAuth } from "isitme/react";

export default function Dashboard() {
  const { session, loading, logout } = useAuth();

  if (loading) return <p>Loading...</p>;
  if (!session) return <p>Not authenticated</p>;

  return (
    <div>
      <p>Authenticated!</p>
      <button onClick={logout}>Log out</button>
    </div>
  );
}

import { SigninForm } from "isitme/react";

export default function AuthPage() {
  return (
    <SigninForm
      onSuccess={() => router.push("/dashboard")}
    />
  );
}

import { LoginForm } from "isitme/react";

<LoginForm
  heading="Welcome back"
  onSuccess={() => router.push("/dashboard")}
/>

import { RegisterForm } from "isitme/react";

<RegisterForm
  heading="Claim this site"
  onSuccess={() => router.push("/")}
/>

shadcn Components

Pre-built auth components for shadcn/ui projects. Install them into your project as editable source files — they use your existing Button and Card components.

Unlike the isitme/react package (which is a dependency you import), these are files you own and customize.

# Login form — passkey sign-in card
npx shadcn@latest add https://isitme.dev/r/login-form.json

# Register form — passkey registration card
npx shadcn@latest add https://isitme.dev/r/register-form.json

# Signin form — auto-detects login vs register
npx shadcn@latest add https://isitme.dev/r/signin-form.json

# Auth gate — renders children only when authenticated
npx shadcn@latest add https://isitme.dev/r/auth-gate.json

# useAuth hook only (no UI)
npx shadcn@latest add https://isitme.dev/r/use-auth.json

import { SigninForm } from "@/components/isitme/signin-form";

export default function AuthPage() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <SigninForm
        onSuccess={() => router.push("/dashboard")}
      />
    </div>
  );
}

Vue Components

Vue 3 composables and components from isitme/vue. Same functionality as the React package, using the Composition API.

<script setup>
import { IsItMe } from "isitme/vue";
</script>

<template>
  <IsItMe>
    <template #default>
      <h1>You're in!</h1>
    </template>
    <template #login="{ login, error }">
      <button @click="login">Sign in with Passkey</button>
    </template>
    <template #register="{ register, error }">
      <button @click="register">Register Passkey</button>
    </template>
    <template #loading>
      <p>Loading...</p>
    </template>
  </IsItMe>
</template>

<script setup>
import { useAuth } from "isitme/vue";

const { session, loading, login, logout } = useAuth();
</script>

<template>
  <p v-if="loading">Loading...</p>
  <div v-else-if="session">
    <p>Authenticated!</p>
    <button @click="logout">Log out</button>
  </div>
  <button v-else @click="login">Sign in</button>
</template>

<script setup>
import { SigninForm } from "isitme/vue";
import { useRouter } from "vue-router";

const router = useRouter();
</script>

<template>
  <SigninForm
    @success="router.push('/dashboard')"
  />
</template>

<script setup>
import { LoginForm } from "isitme/vue";
import { useRouter } from "vue-router";

const router = useRouter();
</script>

<template>
  <LoginForm
    heading="Welcome back"
    @success="router.push('/dashboard')"
  />
</template>

Examples

Complete, runnable examples for every framework. Clone the repo and run any example with pnpm dev.

import express from "express";
import cookieParser from "cookie-parser";
import { isitme } from "@isitme/express";

const app = express();
app.use(cookieParser());
app.use(isitme({ storage: "./auth.json" }));

app.get("/", (_req, res) => {
  res.send("You are authenticated!");
});

app.listen(3002);

Recipes

Common patterns for using isitme in real apps.

import { IsItMe } from "isitme/react";

<main>
  <h1>My App</h1>
  <IsItMe fallback={false}>
    <AdminToolbar />
    <DebugPanel />
  </IsItMe>
  {/* Regular app content — always visible */}
</main>

import { useAuth, SigninForm } from "isitme/react";

export default function Dashboard() {
  const { session, loading, logout } = useAuth();

  if (loading) return <p>Loading...</p>;
  if (!session) return <SigninForm />;

  return (
    <div>
      <h1>Dashboard</h1>
      <button onClick={logout}>Log out</button>
    </div>
  );
}

app.use(isitme({ publicPaths: ["/", "/about", "/pricing"] }));

app.get("/", (req, res) => {
  res.send(req.isAuthenticated ? "Welcome back, boss" : "Public landing");
});

app.get("/admin", (req, res) => {
  // Only the owner can reach this
  res.send("Admin panel");
});

// Only protect API routes — the /admin page loads freely
app.use(isitme({
  protectedPaths: ["/api/admin/"],
  loginPage: false,
}));

// <IsItMe> shows login form until authenticated, then renders children
export default function AdminPage() {
  return (
    <IsItMe>
      <AdminDashboard />
    </IsItMe>
  );
}

<IsItMe
  loginProps={{
    heading: "Welcome back, boss",
    buttonText: "Unlock",
  }}
  registerProps={{
    heading: "Claim this site",
    buttonText: "Set up passkey",
  }}
>
  <Dashboard />
</IsItMe>

// Your existing auth already verified the user
// Add isitme as a biometric second factor

<IsItMe fallback={<p>Verify your identity with a passkey to continue.</p>}>
  <SensitiveSettings />
  <BillingPanel />
  <DangerZone />
</IsItMe>

isitme({
  allowedOrigins: ["myapp.com", "*.myapp.com", "localhost"]
})

Advanced Configuration

Middleware options for self-hosting, credential storage, sessions, and the raw auth routes.

IsitmeOptions

Pass options to isitme() to customize behavior.

isitme({
  publicPaths: ["/", "/about"],
  storage: file("./.credentials.json"),
  sessionMaxAge: 3600,
})

Login Page

isitme ships a built-in login and registration page. Customize it with loginPage options, or disable it with false and handle auth UI yourself.

isitme({
  loginPage: {
    title: "Welcome back",
    brandName: "My App",
    brandColor: "#6366f1",
  },
})

PageOptions

Credential Storage

By default, credentials are stored in isitme's cloud service — no config needed. Just use isitme() with no storage option. For full control, pass a custom storage adapter.

Custom storage

advanced

Pass a storage option to manage credentials yourself. Full control, no external dependencies.

isitme({
  storage: {
    async load() {
      return db.get("isitme_credentials");
    },
    async save(data) {
      await db.set("isitme_credentials", data);
    },
  },
});

Sessions & Guard

Sessions are stored as a signed JWT in an HTTP-only, secure, SameSite=Lax cookie named isitme_session. Set automatically on login, cleared on logout. No session store required.

app.get("/dashboard", (req, res) => {
  if (req.isAuthenticated) {
    res.send("Welcome back!");
  } else {
    res.send("Public content");
  }
});

publicPaths

Routes listed in publicPaths skip the auth redirect. Unauthenticated users can access them but req.isAuthenticated is still set.

isitme({
  publicPaths: ["/", "/about", "/api/health"],
})

Auth Routes

The middleware mounts these endpoints under /_isitme. They power the login page and can be called directly.

{ "authenticated": true, "registered": true }

Manual setup (without an adapter)

If you need fine-grained control over the auth endpoints — for example, in Next.js App Router without edge middleware — you can wire up @isitme/core/edge directly using route handlers. See examples/nextjs/app/api/auth/[...path]/route.ts for a complete reference implementation (~120 lines). The isitme/express, isitme/next, and isitme/hono adapters are the recommended approach for most users.

Recovery

What happens when you lose a device, switch platforms, or need to start fresh.

Passkey sync

Passkeys are synced automatically by your platform's credential manager — iCloud Keychain on Apple devices, Google Password Manager on Android/Chrome, or third-party managers like 1Password. When you register a passkey on one device, it's available on all your devices signed into the same account. Nothing to configure.

Lost device

If you lose a device, your passkeys are still available on any other device synced to the same account. Sign in from another device — your Mac, your phone, a new laptop — and you're back in.

Cross-device login

Need to sign in from a device that doesn't have your passkey? Most browsers support QR code cross-device authentication — scan a QR code with your phone to approve the login on the other device.

Full recovery via DNS

If you lose access to all your devices and your passkey manager, you can re-register by proving domain ownership. Add a DNS TXT record to your domain — isitme verifies it and lets you register a new passkey.

Type:  TXT
Name:  _isitme.yourdomain.com
Value: isitme-verify=<token>

You own the domain — that's all the proof we need. Visit /debug on your site or the admin dashboard to initiate recovery.

Agent Skills

isitme ships with an Agent Skill — a structured instruction file that AI coding assistants can discover and use automatically. When you ask an AI agent to "add passkey auth", it finds the isitme skill and knows exactly which packages to install, how to set up the middleware, and how to wire up the client.

Install the skill

Add the isitme skill to your project with the skills CLI:

Then open your project in any supported tool and tell it to add passkey auth. The skill is also bundled in the npm package — compatible tools discover it automatically when isitme is installed as a dependency.

Supported tools

Any tool that supports the Agent Skills spec will discover isitme automatically. This includes Claude Code, Cursor, Gemini CLI, GitHub Copilot, VS Code, and many more.

What's in the skill

• Quick start instructions for every framework (Express, Hono, Next.js)
• Cloud mode vs local mode setup
• React and browser client integration
• UI gating vs data gating patterns
• Custom storage adapter interface
• Full API reference

Try it

Ask your AI coding assistant:

Troubleshooting

Common issues and how to fix them.