Dashboard Setup

This guide walks you through the dashboard — from signing up to wiring auth in your app. PaperDB has two separate auth layers; understanding both is essential.

Auth layers at a glance

Step 1 — Create a dashboard account

1. Go to /signup on your PaperDB instance (e.g. https://paperdb.app/signup)
2. Enter email and password
3. Land on /dashboard

Your account is used to manage databases and API keys. It is separate from the end-users who sign up through your application.

Step 2 — Create a database

1. On /dashboard, click New database
2. Enter a name (e.g. my-app-prod)
3. Click Create

Each database gets a unique ID and a default API key. The key is shown once in a modal — copy it before closing.

Step 3 — Save your API key

1. Click the copy button in the success modal
2. Paste into .env as PAPERDB_API_KEY
3. Click Got it!

To manage keys later:

1. Open your database from the dashboard home
2. Sidebar → API Keys
3. Create API Key — name it (e.g. Production)
4. Use eye / copy / trash icons to reveal, copy, or revoke

Step 4 — Explore the database sidebar

Collections are created by your application through the SDK — not manually in the dashboard.

Step 5 — Wire SDK auth in your app

Initialize the client with your API key and backend URLs:

import { createClient } from "paperdb-js";

const db = createClient({
  apiKey: process.env.PAPERDB_API_KEY!,
  baseUrl: "https://api.paperdb.app",
  realtimeUrl: "wss://realtime.paperdb.app",
});

Email / password

Works as soon as the API is running. No extra dashboard setup.

const { user, session } = await db.auth.signUp({
  email: "alice@example.com",
  password: "secure-password",
  name: "Alice",
});

const { user, session } = await db.auth.signIn({
  email: "alice@example.com",
  password: "secure-password",
});

Users are scoped to your database. A session token is returned that your app should store and send with subsequent requests.

Magic links

Sends a one-time sign-in link to the user's email. Links expire after 15 minutes.

// 1. Send link (expires in 15 minutes)
await db.auth.sendMagicLink({
  email: "user@example.com",
  redirectUrl: "https://yourapp.com/auth/callback",
});

// 2. On callback page — extract email + token from URL
const { user, session } = await db.auth.verifyMagicLink(email, token);

Password reset (SDK users)

await db.auth.resetPassword("user@example.com");
// User clicks email link (valid 1 hour), then:
await db.auth.confirmResetPassword(email, token, "new-password");

OAuth (Google / GitHub)

Redirects the user to the provider for sign-in. Register these callback URIs in your Google and GitHub OAuth app settings:

• https://api.paperdb.app/auth/oauth/google/callback
• https://api.paperdb.app/auth/oauth/github/callback

// Redirects browser to provider
await db.auth.signInWithProvider({
  provider: "google",
  redirectUrl: "https://yourapp.com/auth/callback",
});

// On callback — token is in the URL query string
const token = new URLSearchParams(window.location.search).get("token");
if (token) db.auth.setSessionToken(token);

Step 6 — Scaffold with the CLI

npx create-paperdb@latest my-app
cd my-app
cp .env.example .env
# Add PAPERDB_API_KEY + baseUrl
npm install && npm run dev

The CLI asks for framework, auth providers, and features, then generates a ready-to-run project. See CLI docs.

Step 7 — Verify

• Insert a document via SDK — collection appears in dashboard sidebar
• Sign up a test user through your app
• If using magic links — trigger one and confirm email delivery

Common issues