Authentication on back(d)

Users and passwords

Mon, 01 Jan 0001 00:00:00 +0000

The backd user commands manage the users of a realm with auth: enabled. They call the realm’s admin API on a running backd, so you first log in as an administrator (or set BACKD_API_KEY to an admin API key). The realm’s first administrator is created with backd bootstrap. Server-side services can call the admin API directly.

backd login --realm blog --url https://api.example.com
backd user list --realm blog

Every command also takes --url, to pick the server for that command.

Sign-up, login and sessions

Mon, 01 Jan 0001 00:00:00 +0000

What a signed-in user may do with data is decided by each collection’s access rules. Server-side services use API keys instead.

Every realm with auth: enabled has its authentication endpoints under /v1/{realm}/_auth. A realm that doesn’t exist or has auth: disabled answers 404 not_found on all of them.

Sessions and tokens

Signing up or logging in returns a session token:

{
 "token": "bds_mxamh1_afbN3BMzfXqDWhxYpXKF58FhWQ4r9eaLc9ew",
 "token_type": "Bearer",
 "session_id": "dars2ql90v6000bbohr0",
 "expires_at": "2026-10-26T12:58:18.988Z",
 "user": {
 "id": "dars2ql90v600434mf0g",
 "email": "ada@example.com",
 "email_verified": false,
 "roles": [],
 "locale": "en",
 "created_at": "2026-09-26T12:58:18.838Z"
 }
}

Send it on every request that needs a signed-in user:

Magic links

Mon, 01 Jan 0001 00:00:00 +0000

A magic link signs a user in with nothing but their mailbox. The email carries a link (opened on the device that asked) and a 6-digit code (typed in the app that asked, on any device); either one works, once, for 10 minutes. It is one more first factor, next to a password and providers: a user with a second factor is still asked for it.

It proves the same thing a password reset does (control of the mailbox), so it is as strong as that.

Re-authentication

Mon, 01 Jan 0001 00:00:00 +0000

A session proves who a request comes from when it started, not that the person is still at the keyboard. Before an action that is hard to undo or that could lock the real user out, backd asks for one fresh proof of identity. It is the same single step for every kind of user, and it replaces the password field that these endpoints used to take.

The proof

POST /_auth/reauth takes the strongest proof the user has:

Multi-factor authentication

Mon, 01 Jan 0001 00:00:00 +0000

A realm can ask for a second factor after the first one. The first factor is whatever the user used to say who they are: a password, a provider or a magic link. The second factor is a one-time code from an authenticator app, or one of ten recovery codes.

The second step is built once and shared by every first factor, so a user with MFA is asked for a code whether they signed in with a password or with Google.

Sign in with Google, Microsoft or Apple

Mon, 01 Jan 0001 00:00:00 +0000

A realm can let its users sign in with Google, Microsoft or Apple. backd runs the redirect flow with the provider, checks the answer, finds or creates the user, and gives your app a one-time code to trade for a session. A user can have a password and any number of providers at once (at most one of each): they are sign-in methods of the same user, so roles, rules and owned documents don’t depend on how the user signed in.

Access rules (rules:)

Mon, 01 Jan 0001 00:00:00 +0000

Each collection of a realm with auth: enabled can have a rules: section in its collection.yaml, next to its schema.json. Rules decide, per operation, whether a caller may act on a whole document. There are no per-field permissions: data that needs different visibility belongs in a separate collection with its own rules.

$CONFIG_DIR/<realm>/<database>/<collection>/
 schema.json
 indexes.json # optional
 collection.yaml # optional — its `rules:` section is the access rules
 rules.test.yaml # optional — tests for the rules

The same file holds the collection’s other policy: files:, soft_delete: and on_owner_delete: (see the collection file). This page is about the rules: key.

Consents

Mon, 01 Jan 0001 00:00:00 +0000

Apps that handle personal data usually have to show people a text (terms, a privacy notice, marketing) and keep proof of what they accepted and when. backd keeps the texts with the rest of the configuration, serves them to apps, and records acceptances in an append-only history.

Note

backd provides the mechanisms. Which texts you need, on which legal basis and for how long you keep the records are decisions for you and your lawyers; nothing here is legal advice.

Declaring consents

In realm.yaml:

API keys

Mon, 01 Jan 0001 00:00:00 +0000

API keys let server-side services (a backend, a worker, a script) call a realm’s data routes. A key belongs to one realm and gives full access to all of that realm’s data, in every database.

Authentication on back(d)

Users and passwords

Sign-up, login and sessions

Sessions and tokens#

Magic links

Re-authentication

The proof#

Multi-factor authentication

Sign in with Google, Microsoft or Apple

Access rules (rules:)

Consents

Declaring consents#

API keys

Sessions and tokens

The proof

Declaring consents