Skip to content

Permissions & access

Permissions control who can see and change what in Danbyte. Access is grant-based: you give people permission to do things - there are no "deny" rules. A person's access is the sum of everything granted to them directly and through the groups they belong to.

Superusers see everything

A superuser account bypasses all permission checks. The built-in Administrator group is the everyday admin role: full access through ordinary grants, including users, groups and permissions. Use the built-in roles and groups below to give everyone else exactly the access they need.

How access is built

Three pieces work together:

Piece What it is
Users The people who sign in.
Groups Named buckets of people. A group carries permissions, tenant access, and built-in role. Put a user in a group and they inherit all of it.
Permissions The actual grants - "may view devices", "may edit prefixes", and so on. You attach them to groups (or directly to users).

The four things a permission can allow on a type of object are view, add, change, and delete.

A few extra capability verbs apply to specific types and are never implied by change: connect (on devices and virtual machines, each its own grant - open a Connect launcher or the SSH terminal), reveal (on device credentials, shared credentials, wireless LANs and IPSec profiles - read the referenced secret), subscribe (on notification channels - self-service opt-in/out), view credits (on SLA agreements - see the service credits an agreement owes), view cost (on support contracts - see and set what a contract costs), set default (on topology views - choose the view Topology opens with for the tenant; tenant admins can without it, and its row limits say which views), view config (on devices and on virtual machines, each its own grant - read the configuration backups from Oxidized; no built-in group holds it, because a config carries secrets), scan (on inventory profiles - start a discovery run with Run now; no built-in group holds it), and grant superuser (on users - see below). The permission form only offers these on the types that use them.

Some jobs on one feature are separate types so they can be granted apart. Compliance triage - acknowledging, snoozing and reopening compliance violations - needs change on Compliance triage, not on Compliance rules: a rule editor does not triage, and a triager does not edit rules. View on Compliance triage shows its entries in the change log. It is tenant-wide; site limits on the grant do not narrow it, but a triager still acts only on objects they can view.

Granting superuser without being one

grant superuser on the user type lets its holder set or clear the Superuser flag on accounts - so a trusted user-admin can promote and demote without holding superuser themselves. The rules keep it contained:

  • It counts only on a grant with no tenant scoping. Superuser is global, so a tenant-narrowed grant carrying the verb is ignored.
  • On an existing superuser's account, a holder may only flip the flags - password, email, and reset links on superuser targets remain superuser-only, so the verb can revoke without inheriting account takeover.
  • Arming grants superuser on an SSO group mapping needs the same verb - the mapping is a superuser grant.
  • Every flip of the flag lands in the change log, whoever makes it.

Without the verb (or superuser), the Superuser checkbox isn't shown, and the API silently ignores the flag - fail closed, as before.

Built-in roles

Danbyte ships three ready-made groups so you don't have to build common roles by hand. They can't be deleted.

Group What members can do
Administrator View, add, change, and delete everything - including managing users, groups, and permissions (its grant names those types) - and see SLA service credits and contract costs (view credits, view cost).
Operator View, add, and change every object except users, groups and permissions - but not delete. Includes compliance triage. No Admin pages or tenant settings.
Read-only View every object except users, groups and permissions; change nothing.

An all-object grant carries only the verbs it lists. The Administrator grant lists view credits and view cost: administrators manage the grants and could give themselves both. Operator and Read-only hold neither, and no built-in group holds reveal, view config, connect or the other capability verbs. Upgrading to 0.18 adds the two verbs to the built-in Administrator grant; a copy of it, or one shared with another group, is left as it is.

Upgrades don't lock anyone out

When permissions were introduced, every existing user was placed into a sensible role automatically (admins → Administrator, read-only accounts → Read-only, everyone else → Operator). Tighten access from there as needed.

All object types leaves out access management

All object types covers every kind of object except Users, Groups and Permissions. A grant reaches those only by naming them, because adding or changing them is administration: whoever may change users, group membership or grants can give themselves anything. Holding change on Users is what makes someone an administrator - it opens the Admin pages and the tenant settings, and the deployment settings too when the grant is not limited to tenants. The Administrator group's grant names the three types; Operator and Read-only do not.

Upgrading to 0.17, where this rule arrived, names the three types on every all-object grant that was an administrator grant:

  • one with view, add, change and delete that is limited neither to sites nor by row constraints (a tenant limit is fine - it stays a tenant admin), and is not the built-in Operator or Read-only grant,
  • one carrying grant superuser,
  • one held only by the Administrator group.

Every other all-object grant loses them: Operator-style, view-only, a site editor's "read all", and a "full control" grant limited to sites or rows - neither limit ever narrowed users, groups and permissions, so its holders would have managed every account. If that would have left nobody able to manage users, the accounts that could get a grant of their own, Kept user management (0.17 upgrade), with the three types and only the verbs each of them had - accounts with different verbs get one grant per set, named with its verbs (Kept user management (0.17 upgrade): view, change). People a custom grant reached come first, the Operator group's members only when nobody else could, and an upgrade note asks you to put your administrators in the Administrator group, then delete those grants. The shared grants stay trimmed, so nobody who joins those groups later inherits user management.

Managing access

These pages live under Admin → Access in the sidebar and are only visible to Administrators and anyone else granted change on Users.

Users

  1. Go to Admin → Access → Users and click Add user.
  2. Fill in the username, email, and name.
  3. Choose how they get a password - see Inviting people.
  4. Set the toggles you need: active, administrator, require two-factor sign-in, and the sign-in source (local account or company directory).
  5. Assign one or more groups and the tenants the user may switch between.
  6. Save.

Groups

  1. Go to Admin → Access → Groups and click Add group.
  2. Give it a name and an optional description.
  3. Save, then attach permissions to it (below).

Built-in groups can be edited but not deleted.

Permissions

A permission is where you decide who may do what, and optionally to which rows.

  1. Go to Admin → Access → Permissions and click Add permission.
  2. Give it a clear name (e.g. "Edit production prefixes").
  3. Choose the object types it applies to - pick specific ones, or All object types. All object types leaves out Users, Groups and Permissions; with it ticked, those three are offered on their own, and ticking them makes the grant an administrator grant. Types are grouped by area - power panels and feeds and cooling sources and feeds, for one, under Power & cooling; cooling intakes and outflows and their templates sit with the other device components under DCIM.
  4. Tick the actions you're granting: view, add, change, delete.
  5. (Optional) Limit it to certain tenants. A tenant named here also grants access to that tenant: members of the group can switch to it without being added to it on their user page - the grant is the authorisation. Leave empty to cover every tenant the person can reach.
  6. (Optional) Limit it to certain sites. This narrows the object types that belong to a site - devices, prefixes, IPs, VLANs, racks, interfaces, services, NAT rules, and the like - to those sites only. An IP address belongs to its prefix's site when it has none of its own. Object types with no site (VRFs, route targets, tags, catalog entries) are unaffected. Leave empty for all sites. The full list is under Which rows belong to a site.

    Shared objects (a prefix or VLAN with no site - e.g. a supernet the whole company allocates from) are readable under a site-scoped grant: they're context everyone needs. They are never writable under one - creating or editing site-less objects is reserved for people whose grant isn't limited to sites. 7. (Optional) Add row constraints to narrow it to matching rows only - for example, only prefixes whose status is active. Without a constraint, the permission covers every row of the chosen types.

    A grant that names Users, Groups or Permissions takes neither a site limit nor row constraints: neither narrows those types, so the save is refused rather than looking narrower than it is. Grant them on their own. 8. Assign the permission to groups and/or users. 9. Save.

Many at once

Tick rows on the Users, Groups or Permissions list to reveal the bulk bar. Like every change to access, a bulk change needs a deployment administrator: a grant limited to tenants is refused.

List Bulk actions
Users Activate, Deactivate and Delete. Nothing else about an account changes in bulk.
Groups Delete.
Permissions Enable, Disable, Edit (the Enabled switch and the Description) and Delete. What a grant reaches and who holds it stay one grant at a time.

Delete first shows what would happen and names each row it keeps, with the reason. Some rows never go, one at a time or many - a single delete answers the same reason, and a single edit refuses the same switch-off:

  • Your own account is neither deleted nor deactivated.
  • A superuser's account is deleted or deactivated only by a superuser, and the last active superuser stays.
  • Built-in groups stay.
  • The built-in Administrator grant is neither deleted nor disabled.
  • The grants and groups you manage users through stay when the change would take all of them, so nobody locks themselves out of this page.

Every account deleted, activated or deactivated in bulk, every group deleted and every grant changed is in the change log. Users and groups have no export.

Endpoint
POST /api/users/bulk-update/ {ids, fields: {is_active}}; ids are whole numbers
POST /api/users/bulk-delete/ {ids, dry_run}
POST /api/groups/bulk-delete/ {ids, dry_run}
POST /api/object-permissions/bulk-update/ {ids, fields} with enabled, description
POST /api/object-permissions/bulk-delete/ {ids, dry_run}

Site roles (local IT, in one click)

A common need is local IT who runs their own site but shouldn't touch others. Rather than hand-build the grants, open Admin → Access → Permissions and click Site role:

  • Site editor - can add, edit, and delete everything in the chosen site(s) - devices, racks, locations, rooms and the rest - and can read everything elsewhere except users, groups and permissions. This is the local-IT recipe: full control of their own site, look-but-don't-touch everywhere else.
  • Site viewer - read-only access to the chosen site(s), and nothing outside them. Use this when someone should only see their own site.

Pick the role, the site(s), and the users or groups to grant it to. Danbyte assembles the underlying permissions for you (a site-scoped edit grant plus an unscoped read grant for the editor; a single site-scoped read grant for the viewer). You can fine-tune or delete those permissions afterwards like any other. Site roles built before rooms and floor plan stacks existed gain them on upgrade; a hand-built grant is left alone.

Both roles can open the sites they cover. Neither can rename or delete a site - that stays with administrators. The roles leave out records synced from other systems and device configuration history (config snapshots and state, DHCP, DNS, Zabbix, BMC, virtualization changes, certificate bindings); grant those on their own when someone needs them.

An editor reads everything by default (the "see all, edit only mine" model, good for cross-site troubleshooting). Tick "Can only see their own sites" for a strict silo - the read-all grant is dropped and they see nothing outside their sites. The silo editor gets a separate - site record grant instead, for viewing their own sites, and a - catalog view grant for the catalogs their objects use.

Both roles read the catalogs their site's objects point at - device types and roles, platforms, manufacturers, statuses, tags, custom fields, VRFs, IP roles, rack, cabinet and module types, cluster types, routing policies, support contracts (without their cost), applications, application groups, device profiles and the like - so the pickers in Add device and an import by name work. They never change those catalogs: that stays with administrators, or with the site editor's own local entries under enhanced site separation.

Upgrading to 0.18

Site roles created earlier gain view on their sites, and the services, NAT rules, VLAN groups, IP ranges, virtual chassis and other types that became site-scoped. Site viewers and silo site editors gain view on the catalogs above. A grant edited away from the role's shape is left as it is.

Upgrading to 0.19

Site roles created earlier gain installed software (the Software tab on their devices and VMs), application flows (applicationflow, the flows of their sites' addresses, prefixes and ranges) and application group assignments (applicationgroupassignment), and site viewers and silo site editors gain view on applications and application groups. A grant edited away from the role's shape is left as it is. They also gain the PRTG rows of their sites' devices and VMs - device links (prtgdevicelink), sensors (prtgsensor) and the review queue (prtgchange) - so the Sensors tab shows to local IT - and the sensor pins (prtgsensorpin) of the Overview's Sensors card, and the per-device sensor overrides (prtgsensoroverride) of the Coverage card. PRTG connections stay with administrators. Last, they gain device profile assignments (deviceprofileassignment), and site viewers and silo site editors view on device profiles (deviceprofile). They also gain the building outlines of their sites (sitemapoutline), and site viewers and silo site editors view on location types (locationtype) and area types (areatype). Site viewers and silo site editors also view the sensitivity labels (sensitivitylabel) their PDF reports are marked with.

Set it up when you create the user

You don't have to make the user first and wire permissions second. The Create user (and Create group) form has a Site-scoped access section: tick it, choose Editor or Viewer, and pick the sites - the same grants are assembled in one step as the account is created. In a tenant with enhanced site separation on, the box is ticked by default (most new accounts there are local IT).

See what a user can actually do

The user's edit page shows an Access banner in plain language - "edits their sites · reads everything · Site 1" - so you don't have to read the raw permission rows to answer "what can this person touch?".

Manage it from the site itself

Every site has an Access tab (open the site, then Access) that lists who's an editor or viewer there and offers Assign people - the same template, pre-scoped to that site. It's the natural place to answer "who runs this site?" without leaving the site.

Letting site editors invite their own viewers

By default only an administrator can grant site access. If you turn on Settings → General → Let site editors invite their own viewers, a local site editor gains an Invite viewer button on the Access tab of the site(s) they edit. They can grant read-only access to their own site only - nothing wider:

  • they can't create new editors (that stays an admin job),
  • they can't reach any site they don't already edit,
  • they pick from the members of the tenant, and grant to people, not groups.

This is enforced on the server, not just hidden in the UI, so it's safe to hand to local IT in a big multi-site deployment. The toggle is off by default.

What 'edit own site' protects

A site-scoped editor can't create, move, or edit an object into a site outside their scope - the server re-checks the saved object and rolls back if it lands out of bounds. That includes the bulk actions: a bulk edit that would move rows to a foreign site is rejected and rolled back, bulk delete requires the delete action (not just change), and bulk-creating interfaces on another site's device is refused. Prefixes are also held to the site's address space: a site editor can only carve child prefixes inside a prefix that already belongs to one of their sites.

Tags and tenants are enforced server-side too

Creating, editing, or deleting tags requires a tag grant, and any write to a tenant (including deleting one) requires a tenant grant - both checked by the API itself, not just hidden in the UI. Listing tenants and switching between them stays open to every member.

What people see

The interface mirrors these grants so nobody is offered a button that would only fail:

  • Sidebar links hide for sections a person can't view. If a whole section becomes empty, its heading disappears too.
  • Add / Edit / Delete buttons hide on list and detail pages when the person lacks the matching grant.
  • When a permission is limited by row constraints, Edit and Delete hide on the specific rows that fall outside it.

The interface hides buttons; the server enforces the rule

Hidden buttons are a convenience. Even if someone reaches a restricted action another way (an old browser tab, a saved link), the server still refuses it.

Picking people outside Admin

Some features name people without being user administration: notification subscriptions, script sharing, a site editor's viewer invite, and user or group custom fields. Their pickers list the active accounts that can work in the tenant - the tenant is on their user page, a permission limited to the tenant names them or their group, or they are a superuser - and the groups those accounts are in, for anyone who works with the feature - no permission on users needed. Superusers and deployment admins see every account. The address is shown only to people who may view users. A spreadsheet import resolves person and group cells against the same list for people without a permission on users.

Inviting people

When you create a user, choose how they get their password:

  • Email an invite (recommended) - the person receives a one-time link to set their own password. You never see or handle their password.
  • Set a password - you type an initial password yourself.

Every password you set - creating a user, editing one, the Django admin, or DJANGO_SUPERUSER_PASSWORD for manage.py bootstrap - must pass the same checks as a password set through a link: at least 8 characters, not too close to the username, name or email, not a common password, and not all digits. The API answers a weak one with a 400 and the reasons under password.

Editing an existing user, the same option lets you email a password-reset link. It starts unticked, so saving an edit sends nothing unless you tick it.

A link is refused once the account is disabled, and setting a password never re-enables an account. Enable the account before sending an invite or reset link; one isn't sent to a disabled account.

Note

Inviting requires an email address on the account and working email settings for your deployment. People who sign in through your company directory don't need a Danbyte password at all.

Invite and reset links, and emailed sign-in codes, go through a tenant's own mail server only for accounts that work in that tenant alone. Those for administrators, and for people in more than one tenant, go through the deployment's mail settings, so a tenant's admin doesn't see them in their relay. If the deployment has no mail server of its own, they use the tenant's instead so they still arrive - set up deployment email to keep them out of tenant relays.

Passwords

Changing your own password

Anyone with a local Danbyte password changes it under Preferences → Password: the current password, then the new one twice. The new password must pass the same checks as one an administrator sets; each failed rule is shown under the field.

  • The browser you change it from stays signed in. Every other session of the account is signed out, including a sign-in waiting for its second factor.
  • API tokens keep working. They are separate credentials: revoke them under Preferences → API tokens if you think they leaked too.
  • A wrong current password counts toward the same lockout as a failed sign-in (10 per address and account, 30 per account, for 15 minutes).
  • The change is in the change log as an update to the user, without the password.
  • Only a signed-in browser session can do it. A request made with an API token is refused.
  • Accounts that sign in through the company directory or single sign-on have no Danbyte password: the card says where the password is managed instead.

Forgot password (reset by email)

Off by default. An administrator turns it on with PASSWORD_RESET_ENABLED (see Settings). Forgot password? then shows on the sign-in page, as long as deployment email is enabled with a mail server of its own (Settings → Email) and the Public base URL is set (Settings → Security → Outbound delivery).

  • Enter your username or email address. The answer is always the same, whether or not the account exists, and the mail goes out in the background.
  • Mail goes only to active accounts with a local password and an email address. Directory, single sign-on, disabled and not-yet-activated accounts get nothing.
  • The link points at the public URL, works once and expires after an hour (PASSWORD_RESET_LINK_TIMEOUT). Signing in with the old password also cancels it. One account gets at most one reset mail a minute.
  • Requests have the same limits as sign-in, counted separately.
  • Setting the new password signs out every session of the account and does not sign you in. Sign in with the new password; two-factor sign-in still applies.

An administrator can still send a reset link from the user's page, as described under Inviting people.

Two-factor sign-in (MFA)

You can require a second step at sign-in for any account, and anyone can add one to their own.

  • Turn it on per user with require two-factor sign-in.
  • People set up their second factor under their own Preferences → Two-factor authentication, using either an authenticator app (scan a QR code) or a 6-digit code sent to their email.
  • An authenticator someone sets up themselves is asked for at every password sign-in (local or directory), whether or not two-factor is required on the account. A code sent to their email also works when the account has an email address and email codes are allowed. Removing the authenticator goes back to the password alone, unless two-factor is required.
  • Single sign-on doesn't ask for Danbyte's second factor: the identity provider authenticates the person, so set up MFA there. API tokens are separate, scoped credentials and don't use it either.
  • An account that requires two-factor but has no second factor yet is asked to set up an authenticator app right after entering its password, and is not signed in until that is done.
  • Removing an authenticator asks for the account's password or a current code. While two-factor is required, the only remaining second factor can't be removed: add an email address first, or have an administrator clear it with danbyte-admin users clear-mfa.
  • An authenticator code is accepted once.
  • The Django admin (/admin/) and the job queue page (/django-rq/) have no sign-in form of their own: they send you to the normal sign-in, second factor included, and back again afterwards.

Company directory (LDAP / Active Directory)

Optional and off by default. When an administrator connects your directory under Settings → Directory, people can sign in with their existing company credentials. Their Danbyte group membership is kept in sync from their directory groups every time they sign in, so the directory decides who's in what and Danbyte groups decide what that means. Only directory groups you've explicitly mapped grant anything.

What a directory login receives

On every LDAP login the account's Danbyte groups are re-synced from the mapped directory groups, and then:

  • Tenants. A group's tenant-scoped grant is tenant access. Those tenants are added to the account's profile at login and the first one becomes the home tenant, so the account lands in the right place and appears in that tenant's user list without an admin editing the record.
  • Superuser. Tick Grants superuser on a deployment-directory mapping and members of that directory group become superusers when they sign in - the same switch an SSO mapping has. Arming it needs the grant-superuser permission, it is not offered on a tenant directory, and a login never clears it: revocation stays a manual act on the user.

A permission whose actions include grant_superuser does not make its holders superusers - it lets them promote others. Use the mapping switch for the accounts that should be superusers themselves.

Single sign-on (SSO)

Optional and off by default. An administrator adds an identity provider under Settings → Identity providers (SSO) - an OpenID Connect (OIDC) or SAML 2.0 provider such as Entra ID, Okta, or Google Workspace. Each enabled provider appears as a Sign in with… button on the login page. When someone signs in through it, Danbyte reads their email, username, and name from the provider's claims and - if just-in-time provisioning is on - creates their account on first login. With just-in-time provisioning off, only accounts you've already created may sign in.

As with the directory, group access is driven by mappings: match a group the provider asserts (for Entra ID, a group object ID) to a Danbyte group, and only mapped groups grant anything. When you add a provider, register the callback URL shown on its edit screen as the redirect URI at your identity provider.