Roles and Permissions

FreeSDN controls access through three complementary mechanisms: a 5-tier role hierarchy, optional per-user site grants, and scoped API keys. Together they give you fine-grained, auditable control over who can do what on which parts of the infrastructure.

---

Role hierarchy

Roles are ordered by numeric level. Each role inherits all capabilities of the roles below it.

Role	Level	Scope	Description
super_admin	100	Cross-org	Full platform access including all organizations. The super_admin role is assigned only during the initial setup wizard - no user can assign the super_admin role via the API (the strict-lower-than rule: a super_admin at level 100 can only assign roles strictly below 100).
org_admin	60	Own org	Operational control within a single org. Full access to all modules, user management, agents, and discovery. Cannot upgrade firmware or modify billing/platform settings.
site_admin	40	Assigned sites	Full control over the sites they are assigned to. Cannot manage org-level users or upgrade firmware.
operator	20	Assigned sites	Day-to-day operations: reboot devices, view config, view logs, monitor VPN (read-only), run discoveries.
viewer	10	Assigned sites	Read-only access to all dashboards and logs. Cannot change anything.

Strict-lower-than role assignment

You can only assign or modify roles whose numeric level is strictly below your own. An org_admin (60) can assign roles up to site_admin (40) but cannot create another org_admin. This is enforced at the API layer and raises HTTP 403 on violation.

---

Permission sets by role

The table below summarises key capabilities per role. ” - ” means the permission is not granted.

Capability	super_admin	org_admin	site_admin	operator	viewer
All permissions (*)	Yes	-	-	-	-
Org / site management	Yes	Yes (own org)	Read	Read	Read
User management	Yes	Create/update	Read	-	-
Firmware upgrade	Yes	-	-	-	-
Device CRUD + reboot	Yes	Yes	Yes	Read + reboot	Read
Network read	Yes	Yes	Yes	Yes	Yes
Network write	Yes	Yes	Yes	-	-
Config push	Yes	Yes	Yes	-	-
VPN read	Yes	Yes	Yes	Yes	Yes
VPN write	Yes	Yes	Yes	-	-
Firewall full	Yes	Yes	Yes	Read	Read
Cameras (view/playback)	Yes	Yes	Yes	Yes	Yes
VoIP management	Yes	Yes	View+phones	View only	View only
Access control (BETA)	Yes	Yes	Yes	View+events	View+events
Hypervisor	Yes	Yes	Yes	Read	Read
AI assistant	Yes	-	-	-	-
Agent management	Yes	Yes	Create+write	Read	-
Discovery run	Yes	Yes	Yes	Yes	-
Audit log read	Yes	Yes	Yes	Yes	Yes
Plugin install	Yes	-	-	-	-
Marketplace sync	Yes	-	-	-	-
Observability (flows/logs)	Yes	Yes	Yes (read)	Read	-

Tip

operator is the recommended role for day-to-day NOC staff. It covers reboots, discovery, VPN monitoring, camera access, and log review - without the ability to change network topology or user accounts.

Caution

Access Control is BETA and off by default. Door lock/unlock endpoints return 501 Not Implemented - no door adapter ships in this release.

---

Per-user site grants

Within an Organization, you can restrict a user to a specific subset of Sites using UserSiteAccess grants:

• A user with at least one site grant is site-limited: all requests are automatically filtered to their granted Sites. Accessing a resource on a non-granted Site returns 403. This applies to site_admin, operator, and viewer roles only.
• org_admin and super_admin users are never site-limited - they always have access to every Site in their org regardless of any UserSiteAccess grants attached to their account (grants on these roles are silently ignored at runtime).
• A user with no site grants has access to all Sites in their org (the backwards-compatible default).

Assigning site grants

Manage site grants from Settings → Users → [user] → Site Access. Grant or revoke individual Sites. Grants take effect immediately - active sessions are re-evaluated on the next request.

Site grants and role interaction

Site grants narrow but never expand a role’s permissions. A viewer with a site grant can only view resources on their granted Sites - the grant does not unlock actions that the viewer role itself does not permit.

---

Scoped API keys

When you create an API key, you select a permission scope from the permissions your account holds. The key is a hard ceiling:

• The key can never exceed the permissions you declared at creation time.
• Even as a super_admin, a scoped key has the super_admin wildcard bypass suppressed - it operates exactly within its declared scope.
• Revoke keys immediately from Settings → API Keys. Revoked keys are rejected on the next request.

Tip

Use scoped API keys for integrations and automation. Give each integration the narrowest scope it needs. Rotate keys on a regular schedule.

---

is_superuser flag

The is_superuser field in API responses is a convenience flag derived from role == "super_admin". It always tracks the role and cannot be set independently - there is no separate persisted column in the database. In code, explicit is_superuser checks and minimum-role checks serve different call-sites but both derive from the same role value. In practice, cross-org operations are available only to users whose role is super_admin.

---

Checking your effective permissions

The API returns your current permission set:

GET /api/v1/auth/me
Authorization: Bearer <token>

The response includes role, permissions, is_superuser, and is_org_admin, plus standard user fields (id, email, organization_id, is_active, mfa_enabled, etc.). Use this to verify what a given credential can do before configuring an integration.

---

Next steps: Security Model - Production Hardening Checklist