You are viewing archived documentation for v0.66. Go to latest →

Settings and permissions by level

Otavi decides things at four levels:

  • Hub: everything on this hub, set by hub admins in Hub settings.
  • Team: each team, set by its admins in Team settings.
  • Account: each person, for themselves, on the Account page.
  • Satellite: each registered phone or Pi, either stored on the hub (its page under Satellites) or kept on the satellite itself (the phone's Settings screen, the Pi's .env).

This page lists every setting and permission with the levels where it exists: where to change something, who may do what, and how a value set at one level meets the others.

Words used here

  • Default: what a level gets when it sets nothing itself, named after where it comes from: "Hub default (Off)", "Team default (On)".
  • Override: a lower level setting its own value instead of the default. The level above can allow it or not: "Teams may override", "Satellites may override".
  • Locked: a level above does not allow overriding. The setting shows its value, greyed, with "Locked by the hub" or "Locked by the team".
  • Hub admin: the hub-wide role (is_platform_admin in the code, where the hub level is still called platform).
  • Device: only the computer or phone someone signs in from, as in the two-factor "remembered devices". A recording phone or Pi is a satellite.

How the levels combine

  • Satellite settings the hub sends (audio filter, upload queue, heartbeat, pre-upload drops): the satellite's own value when it overrides, otherwise the team's, otherwise the built-in default. A satellite's page shows, next to each setting, the default it would get.
  • On-satellite inference hub 0.64: hub, then team, then satellite. Each level sets a value and says whether the level below may override it; a level that does not allow it wins over everything below. A change refused for that reason answers 403 LOCKED_BY_PLATFORM or LOCKED_BY_TEAM (the API codes keep the code names).
  • Hub switches over team options: a team can open itself to newcomers only while allow_public_teams is on, and publish a public page only while allow_public_pages is on.
  • Account over team: a person's bird-name languages win over the team language wherever that person reads names (web pages, PDF and CSV exports, shared links). Alerts and scheduled exports use the team language.

Settings

Legend: ✓ = the setting exists at that level. In the Satellite column, "hub" = stored on the hub for each satellite, "local" = kept on the satellite itself.

Access and joining

Setting Hub Team Account Satellite Default How it resolves Where
Sign-up without an invite (allow_self_registration) ✓ on hub only; an invite always works Hub settings › Access
Team creation by anyone signed in (allow_tenant_creation) ✓ off hub only; hub admins always may Hub settings › Access
Invite links (allow_invite_links) ✓ on shown, not enforced yet Hub settings › Access
Teams people can join or find (allow_public_teams) ✓ off gates the team's joining options below Hub settings › Access
Public team pages (allow_public_pages) ✓ off gates the team's public page Hub settings › Access
How people join (join_policy) ✓ invite only applies while allow_public_teams is on Team › General
Role given to newcomers (default_join_role) ✓ viewer team Team › General
Listed in the team directory (listed) ✓ off needs allow_public_teams Team › General
Public page, with towns (public_page, public_page_places) ✓ off needs allow_public_pages; towns need the page Team › General
Who adds satellites (device_policy) ✓ members team Team › General
Two-factor sign-in ✓ off; required for hub admins account Account

Detection and inference

Setting Hub Team Account Satellite Default How it resolves Where
On-satellite inference ✓ ✓ hub off, every level may override hub > team > satellite (above) Hub settings › Models, Team › Satellites, satellite page
Confidence bands (confidence_high, confidence_low) ✓ 0.85, 0.4 team; used by the hub's inference Team › Detection
Minimum confidence (min_confidence) ✓ 0.1 team; also sent to satellites that run BirdNET Team › Detection
Range filter (range_filter_threshold) ✓ 0.01 team; also sent to satellites that run BirdNET Team › Detection
Votes needed for a verdict (verification_consensus) ✓ 3 team Team › Detection
Temporal aggregation: on, hits needed, window ✓ on, 2, 30 min team Team › Detection
Unconfirmed detections kept for (tentative_retention_hours) ✓ 24 h team; applied by the hub's retention sweep Team › Detection
Non-bird categories shown (show_*) ✓ hidden team Team › Detection
Watchlist species ✓ none team Team › General
Active classifier and embedding model ✓ chosen in the model registry hub Hub settings › Models
Compare mode and its sample rate ✓ single, 10 % hub Hub settings › Models

Audio filter on satellites

The hub sends these to each satellite, which applies them before uploading.

Setting Hub Team Account Satellite Default How it resolves Where
Pre-filter on (filter_enabled) ✓ hub on satellite, else team, else default Team › Satellites, satellite page, phone
Silence floor (filter_min_rms) ✓ hub 0 (off) same same
YAMNet bird threshold (yamnet_min_bird_prob) ✓ hub 0.05 same same
Drop non-bird categories before upload (drop_*_at_satellite) ✓ hub on same same
YAMNet gate at all (Pi) local on the Pi's .env only Pi .env

Upload queue, schedule and communication

Setting Hub Team Account Satellite Default How it resolves Where
Outbox soft cap, hard cap, maximum age ✓ hub 5000 MB, 8000 MB, 720 h satellite, else team, else default Team › Satellites, satellite page, phone
Heartbeat interval ✓ hub 30 s same same
Marked offline after (offline_timeout_minutes) ✓ 5 min team; the offline alert rule has its own delay (15 min) Team › Satellites
Recording profile hub continuous satellite only satellite page, phone
Admin-only settings (config_locked) hub off satellite; when on, only team admins can change its settings, not the satellite itself nor the person who registered it satellite page
Name and position local set at registration; GPS or manual the satellite reports them phone Settings, Pi .env
Archived hub no satellite; the next heartbeat clears it satellite page

Storage, retention and images

All hub level.

Setting Default Where
Retention sweep on (retention_enabled); every retention setting below waits for it off Hub settings › Storage
Audio soft and hard caps 50 GB, 60 GB Hub settings › Storage
Audio kept for, best recordings kept per species, silent chunks kept for 30 days, 10, 6 h Hub settings › Storage
Android releases kept 5 Hub settings › Storage
Gallery photos per species 5 Hub settings › Storage
Wikimedia access token and contact address none Hub settings › Images
iNaturalist as a second photo source, allowed licences off; CC0, CC BY, CC BY-SA Hub settings › Images
Smart square thumbnails on Hub settings › Images
Delay between photo downloads automatic Hub settings › Images

Alerts

Setting Hub Team Account Satellite Default Where
Alert rules ✓ four built-in rules per team Alerts › Rules
Alert channels (email, Slack, Telegram, Google Chat, Discord, webhook) ✓ none Alerts › Channels
Vibrate on each detection local off phone Settings

Display and language

Setting Hub Team Account Satellite Default How it resolves Where
Bird-name languages ✓ ✓ English account, else team, else English (see above) Account, Team › General
Date and time formats, first day of the week ✓ relative dates, 24 h, Monday account Account
Paper size of PDF reports ✓ A4 account Account
Voting controls on detections ✓ off account Detections page
Web interface language and theme English, dark the browser header menu
Phone interface and species language local the phone's language the phone's system language phone

Settings kept on the satellite itself

  • Phone (Settings screen): keep the screen on, record when the app opens, vibrate on detection, GPS on or off and its interval, manual position, name. The phone also remembers whether it was recording, so that an update resumes it.
  • Raspberry Pi (.env, OTAVI_SAT_*): capture mode and audio input, sample rate and chunk length, GPS mode and fixed position, whether the YAMNet gate runs, telemetry interval, data folder, log level. The Pi also holds starting values (inference mode, minimum confidence, range filter, recording profile, YAMNet threshold) that the hub replaces on its first configuration push.

Deployment switches

Set in the hub's .env by whoever runs the server; see Configuration.

  • OTAVI_AUTH_PLATFORM_ADMIN_EMAILS: who becomes a hub admin.
  • OTAVI_AUTH_MFA_ENCRYPTION_KEY: makes two-factor sign-in available.
  • OTAVI_EBIRD_API_KEY: expected species and eBird-based rarity.
  • OTAVI_SMTP_*: every email (welcome, invites, email alerts, emailed exports).
  • OTAVI_HUB_METRICS_TOKEN: the Prometheus metrics endpoint.
  • OTAVI_BACKUP_*: nightly backups.

Permissions

Roles inside a team, lowest first: viewer, member, admin, owner. A hub admin counts as at least admin in every team. The registrant of a satellite is the person who registered it.

"Manage a satellite" means: a hub admin, an admin of the satellite's team, or its registrant while the team's policy is "members". A satellite's own key may act on that satellite only: rename it, rotate its key, edit its settings.

Account

Action Who Gated by
Create an account anyone allow_self_registration, or an invite
Sign in, reset a password, set up two-factor the person –
Change preferences, profile, password; download or delete the account the person neither a team's sole owner nor a hub admin can delete their own account

Teams

Action Who Gated by
Create a team (and own it) anyone signed in allow_tenant_creation; hub admins always may
Browse the directory, join or ask to join anyone signed in allow_public_teams and the team's join policy
Approve or refuse requests, block someone admin –
Invite people admin roles up to admin; bulk invites: viewer or member
Change a role, remove a member admin not the owner
Hand the team to someone else owner, hub admin –
Leave a team any member but the owner –
Read team settings viewer –
Change team settings admin opening up and public pages need the hub switches; on-satellite inference may be locked by the hub
Create a team API key admin (API only) –
Read the activity feed member –

Satellites

Action Who Gated by
See satellites, their settings and history viewer –
Register a satellite member team policy "admins": admins only
Re-register or replace a satellite (after a reinstall) its registrant, an admin, or a member holding a team-owned satellite (its device id, which only the satellite and its managers know, proves it) team policy
Change a satellite's settings whoever manages it, or its own key admin-only settings; on-satellite inference may be locked by the hub or the team
Make a satellite's settings admin-only admin –
Recording profile, software update, logs, archive, delete whoever manages it –
Move a satellite to another team hub admin –
Listen to a satellite live member of the satellite's team –

Detections and data

Action Who Gated by
See detections, audio, analytics, sessions, field notes viewer the team's non-bird visibility
Vote, annotate the spectrogram, comment, pin member votes and annotations need a person signed in, not a key
Share a detection with a public link viewer –
Write field notes member; editing and deleting: the author –
Export detections (CSV, JSON, eBird, iNaturalist, xeno-canto) and PDF reports member –
Scheduled exports admin (API only) –
Refit the confidence calibration admin –

Alerts

Action Who Gated by
Read the alerts inbox viewer –
Mark an alert read member –
Read alert rules and channels viewer –
Create, change, test or delete rules and channels admin built-in rules keep their trigger and cannot be deleted

Hub

Action Who
Hub settings, users, teams, models, Android releases, storage and retention, image cache, audit log, system status hub admin
Delete someone's account hub admin; not another hub admin, nor a team's sole owner (hand the team over first)
Prometheus metrics the metrics token, or a hub admin

Public

Action Who Gated by
Landing page, hub counters, species showcase anyone –
A team's public page anyone allow_public_pages and the team's public page
A shared detection anyone with the link promoted detections only; never the satellite's name or position
Latest Android release anyone –