optima/PERMISSIONS.md

Permission Nodes

This document lists all known permission nodes in the optima-api application, categorized by resource type.

Permission System Overview

The permission system uses a dot-notation format: resource.action[.modifier]

Special Tokens

The permission validator supports special tokens for flexible permission management:

• Asterisk (*): Matches the token and all following tokens (e.g., credential.* grants all credential permissions)
• Question Mark (?): Matches only the specific token (single character wildcard)
• Inclusive List ([a,b,c]): Matches only the tokens in the list
• Exclusive List (<a,b,c>): Matches all tokens except those in the list

Global Permissions

• * - Full access to all resources and actions (typically assigned to administrator role)

Permission Nodes by Resource

Company Permissions

Permission Node	Description	Used In
company.fetch	Fetch a single company	src/api/companies/[id]/fetch.ts
company.fetch.address	View company address information (requires company.fetch as well)	src/api/companies/[id]/fetch.ts
company.fetch.contacts	View all company contacts (requires company.fetch as well)	src/api/companies/[id]/fetch.ts
company.fetch.many	Fetch multiple companies	src/api/companies/fetchAll.ts
company.fetch.configurations	Fetch company configurations (requires company.fetch as well)	src/api/companies/[id]/configurations.ts

Credential Permissions

Permission Node	Description	Used In
credential.create	Create a new credential	src/api/credentials/create.ts
credential.fetch	Fetch a single credential	src/api/credentials/fetch.ts
credential.fetch.many	Fetch multiple credentials	src/api/credentials/fetchByCompany.ts
credential.update	Update a credential	src/api/credentials/update.ts
credential.delete	Delete a credential	src/api/credentials/delete.ts
credential.fields.fetch	Fetch credential fields (requires credential.fetch as well)	src/api/credentials/fetchFields.ts
credential.fields.update	Update credential fields (requires credential.update as well)	src/api/credentials/updateFields.ts
credential.secure_values.read	Read secure values of a credential (requires credential.fetch as well)	src/api/credentials/readSecureValues.ts, src/api/credentials/readSecureValue.ts
credential.sub_credentials.fetch	Fetch sub-credentials of a parent credential (requires credential.fetch as well)	src/api/credentials/fetchSubCredentials.ts
credential.sub_credentials.create	Create a sub-credential on a parent credential (requires credential.fetch as well)	src/api/credentials/addSubCredential.ts
credential.sub_credentials.delete	Remove a sub-credential from a parent credential (requires credential.fetch as well)	src/api/credentials/removeSubCredential.ts

Credential Type Permissions

Permission Node	Description	Used In
credential_type.create	Create a new credential type	src/api/credential-types/create.ts
credential_type.fetch	Fetch a single credential type	src/api/credential-types/fetch.ts
credential_type.fetch.many	Fetch multiple credential types	src/api/credential-types/fetchAll.ts
credential_type.update	Update a credential type	src/api/credential-types/update.ts
credential_type.delete	Delete a credential type	src/api/credential-types/delete.ts

Role Permissions

Permission Node	Description	Used In	Dependencies
role.create	Create a new role	src/api/roles/create.ts
role.read	Fetch a single role or view role information	src/api/roles/fetch.ts
role.list	Fetch all roles	src/api/roles/fetchAll.ts	role.read
role.modify	Update role properties or manage role permissions	src/api/roles/update.ts, src/api/roles/addPermissions.ts, src/api/roles/removePermissions.ts
role.delete	Delete a role	src/api/roles/delete.ts
user.read	View users assigned to a role	src/api/roles/getUsers.ts	role.read

User Permissions

Permission Node	Description	Used In	Dependencies
user.read	Read user information	src/api/user/@me/fetch.ts
user.write	Update user information	src/api/user/@me/update.ts
user.read.other	Read other users' information	src/api/user/fetch.ts, src/api/user/fetchRoles.ts, src/api/user/checkPermission.ts
user.list.other	List all users	src/api/user/fetchAll.ts	user.read.other
user.write.other	Update other users' information	src/api/user/update.ts
user.roles.other	Modify roles assigned to other users	src/api/user/update.ts	user.write.other
user.permissions.other	Modify direct permissions assigned to other users	src/api/user/update.ts	user.write.other
user.delete.other	Delete other users	src/api/user/delete.ts

Permission Routes

Permissions required for accessing the permission node definitions API.

Permission Node	Description	Used In
role.read	Fetch all permission nodes organized by category	src/api/permissions/fetchAll.ts
role.read	Fetch a flat list of all permission nodes	src/api/permissions/fetchNodes.ts
role.read	Fetch permission nodes by category	src/api/permissions/fetchByCategory.ts

UI Navigation Permissions

Permissions for controlling navigation visibility on the frontend.

Permission Node	Description	Usage Pattern
ui.navigation.*.view	View specific navigation sections (e.g., ui.navigation.admin.view)	Control which navigation menu items are displayed

Admin UI Permissions

Admin-specific UI permissions that control visibility and data loading for admin sub-tabs.

Permission Node	Description	Usage Pattern
admin.users.view	Show the Users tab and load user data	Show/hide users tab, allow user list fetch
admin.roles.view	Show the Roles tab and load role data	Show/hide roles tab, allow role list fetch
admin.credential-types.view	Show the Credential Types tab and load type data	Show/hide types tab, allow type list fetch

Notes on UI Permissions

• Client-side validation is not secure: Always enforce permissions on the API level. UI permissions only control visibility and user experience.
• Combine with API permissions: A user with an admin UI permission should also have the corresponding API permission (e.g., role.list) to actually load data.
• Use wildcards for flexibility: Grant ui.navigation.*.view to allow all navigation sections.

Procurement Permissions

Permission Node	Description	Used In	Dependencies
procurement.catalog.fetch	Fetch a single catalog item	src/api/procurement/[id]/fetch.ts
procurement.catalog.fetch.many	Fetch multiple catalog items or count	src/api/procurement/fetchAll.ts, src/api/procurement/count.ts
procurement.catalog.inventory.refresh	Refresh on-hand inventory for a catalog item from ConnectWise	src/api/procurement/[id]/refreshInventory.ts	procurement.catalog.fetch
procurement.catalog.link	Link or unlink catalog items to each other	src/api/procurement/[id]/link.ts, src/api/procurement/[id]/unlink.ts	procurement.catalog.fetch

Sales Permissions

Permissions for accessing and managing sales opportunities. Opportunities are synced from ConnectWise and stored locally; sub-resources (forecasts, notes, contacts) are fetched live from CW.

Permission Node	Description	Used In	Dependencies
sales.opportunity.fetch	Fetch a single opportunity and its CW sub-resources (forecasts, notes, contacts)	src/api/sales/[id]/fetch.ts, src/api/sales/[id]/forecasts.ts, src/api/sales/[id]/notes.ts, src/api/sales/[id]/contacts.ts
sales.opportunity.fetch.many	Fetch multiple opportunities (paginated/searchable) or get opportunity count	src/api/sales/fetchAll.ts, src/api/sales/count.ts
sales.opportunity.refresh	Refresh a single opportunity's local data from ConnectWise	src/api/sales/[id]/refresh.ts	sales.opportunity.fetch

UniFi Permissions

Permissions for accessing and managing UniFi network infrastructure. The unifi.access permission is a gate permission required for all UniFi routes.

Permission Node	Description	Used In	Dependencies
unifi.access	Gate permission for the entire UniFi API — required for all	src/api/unifi/sites/fetchAll.ts, src/api/unifi/sites/sync.ts, src/api/unifi/site/fetch.ts, src/api/unifi/site/overview.ts, src/api/unifi/site/devices.ts, src/api/unifi/site/wifi/fetchAll.ts, src/api/unifi/site/wifi/update.ts, src/api/unifi/site/networks.ts, src/api/unifi/site/link.ts, src/api/unifi/site/unlink.ts, src/api/companies/[id]/unifiSites.ts, src/api/unifi/sites/create.ts
unifi.sites.create	Create a new site on the UniFi controller	src/api/unifi/sites/create.ts	unifi.access
unifi.sites.fetch	Fetch a single UniFi site	src/api/unifi/site/fetch.ts	unifi.access
unifi.sites.fetch.many	Fetch all UniFi sites	src/api/unifi/sites/fetchAll.ts	unifi.access
unifi.sites.sync	Sync sites from the UniFi controller into the database	src/api/unifi/sites/sync.ts	unifi.access
unifi.sites.link	Link or unlink a UniFi site to/from a company	src/api/unifi/site/link.ts, src/api/unifi/site/unlink.ts	unifi.access
unifi.site.overview	View live site overview from the UniFi controller	src/api/unifi/site/overview.ts	unifi.access
unifi.site.devices	View live device list from the UniFi controller	src/api/unifi/site/devices.ts	unifi.access
unifi.site.wifi	View WiFi networks (WLANs) from the UniFi controller	src/api/unifi/site/wifi/fetchAll.ts	unifi.access
unifi.site.wifi.read	Field-level gate for WiFi response data (see note below)	src/api/unifi/site/wifi/fetchAll.ts	unifi.access, unifi.site.wifi
unifi.site.wifi.read.<field>	Read a specific field from WiFi response (e.g. unifi.site.wifi.read.passphrase)	src/api/unifi/site/wifi/fetchAll.ts	unifi.access, unifi.site.wifi, unifi.site.wifi.read
unifi.site.wifi.update	Update a WiFi network on the UniFi controller	src/api/unifi/site/wifi/update.ts	unifi.access, unifi.site.wifi

Field-Level Permission Gating (unifi.site.wifi.read)

The WiFi fetch route uses processObjectValuePerms to filter each WLAN object on a per-field basis. For every key on the WlanConf response object, the system checks unifi.site.wifi.read.<key>. Only fields the user has permission for are included in the response. Use unifi.site.wifi.read.* to grant access to all fields.

Available field-level nodes:

unifi.site.wifi.read.id, unifi.site.wifi.read.name, unifi.site.wifi.read.siteId, unifi.site.wifi.read.enabled, unifi.site.wifi.read.security, unifi.site.wifi.read.wpaMode, unifi.site.wifi.read.wpaEnc, unifi.site.wifi.read.wpa3Support, unifi.site.wifi.read.wpa3Transition, unifi.site.wifi.read.wpa3FastRoaming, unifi.site.wifi.read.wpa3Enhanced192, unifi.site.wifi.read.passphrase, unifi.site.wifi.read.passphraseAutogenerated, unifi.site.wifi.read.hideSSID, unifi.site.wifi.read.isGuest, unifi.site.wifi.read.band, unifi.site.wifi.read.bands, unifi.site.wifi.read.networkconfId, unifi.site.wifi.read.usergroupId, unifi.site.wifi.read.apGroupIds, unifi.site.wifi.read.apGroupMode, unifi.site.wifi.read.pmfMode, unifi.site.wifi.read.groupRekey, unifi.site.wifi.read.dtimMode, unifi.site.wifi.read.dtimNg, unifi.site.wifi.read.dtimNa, unifi.site.wifi.read.dtim6e, unifi.site.wifi.read.l2Isolation, unifi.site.wifi.read.fastRoamingEnabled, unifi.site.wifi.read.bssTransition, unifi.site.wifi.read.uapsdEnabled, unifi.site.wifi.read.iappEnabled, unifi.site.wifi.read.proxyArp, unifi.site.wifi.read.mcastenhanceEnabled, unifi.site.wifi.read.macFilterEnabled, unifi.site.wifi.read.macFilterPolicy, unifi.site.wifi.read.macFilterList, unifi.site.wifi.read.radiusDasEnabled, unifi.site.wifi.read.radiusMacAuthEnabled, unifi.site.wifi.read.radiusMacaclFormat, unifi.site.wifi.read.minrateSettingPreference, unifi.site.wifi.read.minrateNgEnabled, unifi.site.wifi.read.minrateNgDataRateKbps, unifi.site.wifi.read.minrateNgAdvertisingRates, unifi.site.wifi.read.minrateNaEnabled, unifi.site.wifi.read.minrateNaDataRateKbps, unifi.site.wifi.read.minrateNaAdvertisingRates, unifi.site.wifi.read.settingPreference, unifi.site.wifi.read.no2ghzOui, unifi.site.wifi.read.privatePreSharedKeysEnabled, unifi.site.wifi.read.privatePreSharedKeys, unifi.site.wifi.read.saeGroups, unifi.site.wifi.read.saePsk, unifi.site.wifi.read.schedule, unifi.site.wifi.read.scheduleWithDuration, unifi.site.wifi.read.bcFilterList, unifi.site.wifi.read.externalId | unifi.site.networks | View network configurations from the UniFi controller | src/api/unifi/site/networks.ts | unifi.access | | unifi.site.wlan-groups | View WLAN groups (AP broadcasting groups) from the UniFi controller for a site | src/api/unifi/site/wlanGroups.ts, src/api/unifi/site/wlanGroupsCreate.ts | unifi.access | | unifi.site.wlan-groups.create | Create a new WLAN group (AP broadcasting group) on the UniFi controller | src/api/unifi/site/wlanGroupsCreate.ts | unifi.access, unifi.site.wlan-groups | | unifi.site.access-points | View access points (UAPs only) from the UniFi controller for a site | src/api/unifi/site/accessPoints.ts | unifi.access | | unifi.site.ap-groups | View AP groups — shows which APs are grouped together for SSID broadcasting | src/api/unifi/site/apGroups.ts | unifi.access | | unifi.site.wifi-limits | View WiFi SSID limits per AP per radio band | src/api/unifi/site/wifiLimits.ts | unifi.access | | unifi.site.speed-profiles | View speed limit profiles (user groups) from the UniFi controller | src/api/unifi/site/speedProfilesFetchAll.ts, src/api/unifi/site/speedProfilesCreate.ts | unifi.access | | unifi.site.speed-profiles.create | Create a new speed limit profile (user group) on the UniFi controller | src/api/unifi/site/speedProfilesCreate.ts | unifi.access, unifi.site.speed-profiles | | unifi.site.wifi.ppsk | View private pre-shared keys (PPSKs) for a specific WiFi network | src/api/unifi/site/wifi/ppskFetchAll.ts, src/api/unifi/site/wifi/ppskCreate.ts | unifi.access, unifi.site.wifi | | unifi.site.wifi.ppsk.create | Create a private pre-shared key on a specific WiFi network | src/api/unifi/site/wifi/ppskCreate.ts | unifi.access, unifi.site.wifi, unifi.site.wifi.ppsk |

Permission Issuers

Permissions can be issued by different sources:

• roles - Permissions granted through role assignment
• user - Permissions granted directly to a user
• api_key - Permissions associated with an API key

Permission Validation

The authorization middleware (src/api/middleware/authorization.ts) enforces permissions by:

1. Extracting the authorization header (Bearer token or API Key)
2. Validating the session/token
3. Checking if the user has all required permissions for the route
4. Throwing an InsufficentPermission error (403) if any required permission is missing

Usage Example

// Require single permission
authMiddleware({ permissions: ["credential.fetch"] })

// Require multiple permissions (all must be satisfied)
authMiddleware({
  permissions: ["credential.fetch", "credential.secure_values.read"]
})

// Administrator role with wildcard permission
{
  moniker: "administrator",
  permissions: ["*"]  // Grants all permissions
}

Notes

• Multiple permissions in a single route require all permissions to be satisfied (AND logic)
• The * wildcard permission grants access to everything in the application
• Permissions are signed using JWT with a private key for integrity
• Permission validation supports pattern matching for flexible permission management