Skip to content

Overview

PrefsDB lets a web page or a script store data without a backend of its own and without asking its users to sign up. This page explains how the pieces fit together: where keys come from, what a request looks like, how data is organized and kept apart, and when PrefsDB is not the right tool.

Keys

Every request carries an API key, and a key can only ever see its own data. There are four ways to get one:

How Who it's for What it needs
getkey(name, seed) Each user of your app, with no account anywhere A name and a secret seed (a passphrase, or a recovery phrase). The same name and seed on the same site always give back the same key.
Signing in with Google, Microsoft, Apple or GitHub Each user of your app, who'd rather not remember a seed The user signs in with that provider; the same person gets the same key on your site every time.
Your dashboard (server-side keys, agent pairing) Your own server, scripts, or an AI agent A PrefsDB account. These keys work on their own, with no session, and can be made read-only, limited to one project, or set to expire.
A sandbox.prefsdb.com email address You, while you build and test Nothing: a test key works at once, for a day. See Testing without an inbox.

A key from getkey() also needs the user's email address the first time, unless the site sponsors its users' keys (see Verify the email address). The key works once the link in the email is clicked; waitForVerification() tells your app when that has happened.

Each of these is a separate key: the same person signing in with Google and later with GitHub, or with a seed, gets different keys with different data, and they aren't linked. Offer one way in, or tell your users which one they used (sign-in buttons can remind them).

A key belongs to the site it was made on (the page's address), so two sites that happen to use the same name and seed get two different keys, just as they'd get two different localStorages.

Sessions

A key from getkey() or a sign-in comes with a short session: proof that whoever uses the key knew the seed (or signed in) a moment ago. The JavaScript client keeps it and renews it for you. Over plain HTTP, the session is in the getkey response as session.token, and you send it back in an X-Prefs-Session header. Dashboard keys need no session.

Requests and responses

The API is plain HTTPS: https://prefsdb.com/api/v1/<operation>/. The key goes in a header, X-Authorization: Token <key>. Key names are query parameters: read/?theme= reads the key theme. Every request can come from any website.

Every response is JSON with success. When something goes wrong, error is a code that never changes (such as SESSION_EXPIRED or VALUE_TOO_LARGE) and message explains it in words: check the code, not the message. See Error codes. Every endpoint is also described in a machine-readable openapi.json.

How data is organized

  • Keys and values: db.key("theme").write("dark"). Writing a key again replaces its value. Values are text up to 1 MB (4 MB on Plus, 8 MB on Pro); objects are stored as JSON.
  • Lists: db.list("todos").add(item) appends; a list can hold the same value many times.
  • Maps: db.map("inventory").put("apples", 8), a named set of keys and values.
  • Files: putObject(file) stores a file, encrypted at rest, with an optional link to share it.
  • Scopes: project(), domain() and subdomain() are labels of your own that group values, like folders. Read with the same labels you wrote with.
  • Expiry: a value can be given a time to live in days; by default nothing expires.

See Grouping data for lists, maps and scopes in detail.

Isolation

Each key's data is kept apart from every other key's on the server itself: every database query is tied to the key making the request, so one key can never read or change another's data, whatever it sends. Each key also has its own limits on requests and storage, so one busy user can't slow down or use up anyone else's allowance. Values can additionally be encrypted in the browser with a key that never reaches PrefsDB.

Who pays

Developers don't. Every key gets a free allowance, and a user who needs more upgrades their own key, so your costs don't grow with the number of your users. See the introduction.

When PrefsDB isn't the right fit

  • Data shared between users. Each key's data is private to that key. Users can send each other messages through channels, but there's no shared table everyone reads from.
  • Queries across data. PrefsDB looks values up by key, scope and list; it has no joins, sorting by value or full-text search.
  • Large or heavy workloads. Values are capped at 1 MB (8 MB on the largest plan) and each key has request limits; it's meant for an app's settings, state and small documents, not analytics or media libraries.
  • Data you must never lose without a backup. A user who loses their seed (and has no other way in) loses access to their key. Offer a recovery phrase or sign-in. Every key comes with a private page (reviewUrl()) where its user can see and download their data.