Realm settings (realm.yaml)

Every realm directory must contain a realm.yaml. It holds the settings that apply to the whole realm: its users, how they sign in, and which browser origins may call it.

$CONFIG_DIR/<realm>/realm.yaml

If a realm has no realm.yaml, backd refuses to start and names the realm. Create a commented starter file with:

CONFIG_DIR=./config backd template realm --realm <realm>

Example#

auth: enabled
signup: invite
sessions:
  idle_timeout: 14d
  max_lifetime: 60d
password:
  min_length: 14
cors:
  origins:
    - https://app.example.com
    - http://localhost:5173
roles:
  admin:
    description: Manages users and invitations
    admin: true
    users:
      - ops@example.com
      - email: lead@example.com
  editor:
    description: Can publish articles

An empty file, or one with only comments, is valid: every key has a default.

Keys#

Durations are a whole number of days (30d) or Go durations (12h, 90m), with a minimum of one minute.

signup, sessions, password, login_throttle, roles, admin, audit, email, account, functions.log_retention and functions.job_retention only apply when auth is enabled. Setting them in a realm with auth: disabled is an error, so a realm can’t carry settings that do nothing. cors and functions.max_concurrency apply either way.

CORS#

Browsers only let a web page call backd from another origin if the realm allows that origin. List the origins of your web apps under cors.origins:

cors:
  origins:
    - https://app.example.com
    - http://localhost:5173

• The list applies to every route of the realm: data, /_auth and /_admin.
• Preflight requests (OPTIONS) from a listed origin get 204 with the allowed methods (GET, POST, PUT, PATCH, DELETE) and request headers (Authorization, Content-Type, If-Match, Idempotency-Key, Prefer, X-Request-ID). The answer may be cached for 10 minutes.
• Every response under /v1/ carries Vary: Origin, so caches keep answers for different origins apart (see Caching).
• Responses to listed origins, errors included, carry Access-Control-Allow-Origin and expose ETag, Idempotent-Replayed, Location, Preference-Applied, Retry-After, WWW-Authenticate and X-Request-ID.
• Credentials travel in the Authorization header, so responses don’t allow credentials, except in a realm with session cookies (sessions.cookie): there, responses to the listed origins carry Access-Control-Allow-Credentials: true, and a wildcard origin is refused.
• X-Backd-On-Behalf-Of isn’t allowed from browsers: only server-side services with API keys may use it.
• * allows any origin. That’s reasonable for public, read-only data; for apps with users, list the origins explicitly.

CORS only tells browsers which pages may read responses. It isn’t access control: requests from other origins, and from anything that isn’t a browser, still go through authentication and access rules.

Account#

account:
  require_verified_email: false
  welcome_email: false
  allow_email_change: false
  purge_unverified_after: 30d
  tokens:
    verify_email: 48h
    reset_password: 1h
    change_email: 24h
    revert_email_change: 7d

Each of require_verified_email, welcome_email, allow_email_change and purge_unverified_after needs the email section: without one, startup fails naming the key. What they do is described in Email verification.

Roles#

Each key under roles declares a role name. Role names follow the same rules as realm names: lowercase letters and digits, optionally separated by single - or _.

• description is optional and only for readers.
• admin makes it an admin role: sessions of users holding it can use the admin API, as admin API keys can. admin: true opens every area of it to change; admin: read is a read-only level for developers (every area to read, users and data only if admin.read_access grants them, nothing to change); a list opens only those areas: admin: [users, invitations], and may include read: admin: [read, secrets] reads everything and changes secrets. The areas are users, invitations, apikeys, secrets, audit, functions, data and config; a user’s roles add up. See Admin rights for what each opens and the rules that stop an administrator from handing out more than they hold. backd bootstrap gives a realm’s first administrator a role with admin: true. Several roles can be admin roles. At startup, backd warns about a realm that declares no admin role, one with no role that has admin: true, or whose admin roles nobody holds (in realm.yaml or the database).
• users lists the users who get the role: plain email addresses, or objects with an email key (- email: lead@example.com). These are seed assignments: they are applied by backd provision and every time backd serve starts, and to a listed email as soon as that user signs up or is created. They add the role and never remove it.

Other assignments can be made later with backd user add-role or the admin API, without editing the file; those live only in the database. At startup, backd logs how many users have assignments that realm.yaml doesn’t list, and warns about users holding roles that realm.yaml no longer declares.

Access rules check roles with hasRole(user, 'admin') or 'admin' in user.roles. Changes to a user’s roles apply from their next request.

Emails are trimmed and lowercased, and each can appear only once per role.

Network restrictions#

Three settings limit where people may act from. Client addresses come from TRUSTED_PROXIES, so every one of these depends on it being exact: behind a proxy without it, every request seems to come from the proxy.

admin:
  allowed_networks: [10.20.0.0/16, "2001:db8:20::/48"]
roles:
  ops:
    admin: true
    users:
      - email: ada@example.com
        admin_networks: [10.20.1.0/24]     # her admin API requests
        login_networks: [10.20.0.0/16]     # her login and her session
      - bob@example.com                    # no restrictions of his own

• An empty or missing list means no restriction. At startup, backd logs (at info) each realm whose admin API is reachable from any network.
• A user’s networks set in realm.yaml are applied like role seeds, at startup and when the user is created, and they win over changes made elsewhere. Networks set for users realm.yaml doesn’t cover live only in the database; startup logs how many users have them.
• An email listed in several roles must have the same networks everywhere.
• API keys can be limited too, when they’re created.

Storage#

A realm that lets documents carry files connects its own S3-compatible bucket with a storage: section: the provider, bucket, a required prefix, and the access keys as secret:NAME references to realm secrets. See Connecting storage and the page of your provider (AWS S3, MinIO, Cloudflare R2, DigitalOcean Spaces). backd template realm writes it commented, with an example for each.

Validation#

realm.yaml is read strictly. backd refuses to start, naming the file, when:

• the realm has no realm.yaml;
• the YAML is invalid or has an unknown key (a typo such as idle_timout is an error, not ignored);
• a value is out of range or not one of the allowed values;
• a user setting is present while auth is disabled;
• a role name or email address is invalid, or an email is listed twice for a role;
• a network is invalid, a user’s admin_networks isn’t within admin.allowed_networks, or an email has different networks in two roles.