Authentication on backd

Command-line administration

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

The backd binary is also the command-line client for administering a realm. backd user and backd apikey don’t touch MongoDB: they call the realm’s admin API on a running backd, as an administrator. They never need database credentials, and every change they make goes through the same checks as any other admin request, including network restrictions.

Two commands write to MongoDB directly instead: backd bootstrap, which creates a realm’s first administrator, and backd secret rotate-key, which re-encrypts every realm’s secrets under a new master key (see Secrets).

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:

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.

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.

Admin API

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

The admin API manages the users and API keys of a realm. backd user and backd apikey are command-line clients of it (see Command-line administration), and server-side services can call it directly. It lives under /v1/{realm}/_admin in every realm with auth: enabled.

Every request needs one of the realm’s API keys with the admin role, acting as itself, or the session of a user holding one of the realm’s admin roles:

Credential	Answer
API key with the `admin` role	Allowed
Session of a user holding an admin role (`admin: true` in `realm.yaml`)	Allowed
Session of a user whose admin role opens only some areas	Allowed for those areas; `403 forbidden` naming the missing one for the rest
API key with the `data` role	`403 forbidden`
None, or an invalid key	`401 unauthenticated`
Session of a user without an admin role	`403 forbidden`
`X-Backd-On-Behalf-Of` with any credential	`400 invalid_header`: admin calls never act as another user

Admin UI

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

The admin UI is a web interface for realm administrators and developers. It is a client of the Admin API and nothing more: it can do nothing the CLI can’t, and every call it makes is authenticated, network-checked and audited by the server like any other. This page is the start of its guide; each area of the interface (users, keys, secrets, audit, functions, data, configuration) is added to it as the area ships.

Audit trail

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

Each realm with auth: enabled keeps an audit trail: one record per security-sensitive action or event, with who did it, to what, when and from where. It answers questions such as “who gave Bob the admin role?” or “which key created this user?”. Records can be read, but not changed or deleted: they expire after the realm’s retention period.

What is recorded

Action	When	Details
`user.create`	An administrator (or `backd bootstrap`) creates a user	`password` (whether one was set), `roles` (seeded from `realm.yaml`)
`user.signup`	A user signs up	`invited`, `roles`
`user.password`	An administrator sets a user’s password
`user.password_change`	A user changes their own password
`user.verify_email`	An administrator marks an email as verified, or not; or a user verifies it with the link in their email	`verified`
`user.password_reset`	A user sets a new password with a reset link	`verified_address`
`user.email_changed`	A user’s address changes: confirmed by the new address, or set by an administrator	`by` (`self` or `admin`)
`user.email_change_reverted`	The old address undid a change
`user.purged_unverified`	A worker deletes accounts that never verified their address	`count`, `older_than`
`function.invoke_manual`	An administrator runs a function by hand (admin API)	`as` (the user’s id, never their email, or null)
`files.versions.regenerate`	An administrator runs `backd files regenerate` (admin API)	`version`, `missing_only`, `job_id`
`storage.reconcile`	An administrator runs `backd storage reconcile` (admin API)	`delete`, `orphans` (how many were found), `deleted`
`storage.check`	An administrator runs a storage check (admin API); never the keys or anything stored	`ok`, `provider`, `bucket`
`data.check`	An administrator starts a schema check (admin API); the target is `data:<database>/<collection>`, `data:<database>` or `data:*`; never the report	`collections`, `limit`, `job_id`
`schedule.pause`, `schedule.resume`	An administrator pauses or resumes a function’s schedule (admin API); only a change is recorded; the target is `schedule:<database>/<function>`	none
`job.cancel`, `job.rerun`	An administrator cancels a job, or queues a finished one again (admin API); the target is `job:<id>`	`function`; for a re-run also `new_job`
`user.disable`, `user.enable`	An administrator disables or re-enables a user
`user.delete`	An administrator erases a user (the tombstone is made; the data work is in the job)	`job_id`
`user.erased`	The erase job finished, or failed for good	`job_id` and `counts` per `database/collection/operation`; `needs_attention` and `error` when it failed. Never content
`user.delete_account`	A user deletes their own account (it is deactivated, not erased)
`user.networks`	A user’s network restrictions change, through the API or from `realm.yaml`	`admin_networks`, `login_networks`
`role.add`, `role.remove`	A role is assigned or taken away, through the API or from `realm.yaml` seeds	`role`
`apikey.create`, `apikey.revoke`	An API key is created or revoked	`role`, `networks`, `expires_at`
`invitation.create`, `invitation.revoke`	An invitation is created or revoked	`bound_to_email` (whether it is), `expires_at`
`invitation.sent`	An invitation is emailed to its address	`expires_at`
`admin.login`	A user holding an admin role logs in	`session_id`
`data.create`, `data.update`, `data.delete`, `data.restore`, `data.purge`	A document is written through the admin data route (a batch audits each operation)	`database`, `collection`, `id`; the target is `doc:<database>/<collection>/<id>`; never content
`session.revoke`	An administrator ends a user’s session (admin API)	`session`
`admin.refused`	An admin API request is refused: by a network restriction, or because the administrator’s roles don’t open the area or hold the rights of the user or role involved	`reason`, `method`, `path`
`realm.bootstrap`	`backd bootstrap` creates the realm’s first administrator	`role`

Failed logins aren’t recorded here: they are throttled and counted, and every request is in the access log.

Deleting and erasing users

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

backd separates two things people call “deleting an account”:

What	Who	Effect	Reversible
Deactivate	the user (`DELETE /_auth/me`, with their password), or an administrator (`PATCH /_admin/users/{id}` with `disabled`, `backd user disable`)	the user is disabled and every session ends; all data is kept	yes: an administrator reactivates (`backd user enable`)
Erase	an administrator (`DELETE /_admin/users/{id}`, `backd user delete --yes`)	the user becomes a tombstone, and the policies of your collections are applied (below)	no

Security model

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

This page summarizes how backd protects data in realms with auth: enabled, and what the operator is responsible for. To report a vulnerability, see SECURITY.md.

Who can do what

Caller	Proves identity with	Can
Anonymous	nothing	What access rules allow `user == nil`
User	session token (`bds_…`)	What access rules allow that user; manage their own account and sessions
Server-side service	API key (`bdk_…`) with the `data` role	Everything in the realm’s data; act as a user with `X-Backd-On-Behalf-Of`
Management tooling	API key with the `admin` role	The same, plus the admin API: users, roles, invitations, API keys
Administrator	session of a user holding an admin role, for example through `backd login`	What access rules allow that user, plus the admin API
Operator	access to `CONFIG_DIR` and MongoDB	Everything, including creating a realm’s first administrator with `backd bootstrap`

Credentials belong to one realm and are unknown in every other realm. Invalid, expired or revoked credentials are always refused (401), never downgraded to anonymous access.

Authentication on backd

Command-line administration

Users and passwords

Sign-up, login and sessions

Sessions and tokens#

API keys

Access rules (rules:)

Admin API

Admin UI

Audit trail

What is recorded#

Deleting and erasing users

Security model

Who can do what#

Sessions and tokens

What is recorded

Who can do what