Permissions & Security

Permissions Engine & Security Guide

Understand how the 42-point permission matrix, plan-based feature gating, API key security, and multi-tenant isolation work on BrandedClaws.

How the Permissions Engine Works

BrandedClaws uses a layered permission system with three levels:

1. Plan Tier Gates

Features are automatically locked or unlocked based on the tenant's subscription plan. A Starter user cannot access Voice AI or Business ERP regardless of manual settings.

2. Granular Feature Permissions

Within an active plan, Superadmins can grant or revoke individual feature permissions per user (e.g., allow a user to view Social Suite but not publish).

3. Superadmin Overrides

Superadmins can grant any individual user access to features beyond their plan tier — useful for trials, custom enterprise agreements, or support access.

Managing User Permissions (Superadmin)

  1. Go to Admin Center → User Management
  2. Find the user and click Edit Permissions
  3. Use the toggles to enable/disable individual feature permissions
  4. Click Save Permissions — changes take effect immediately on the user's next action

Permissions can also be set at a plan tier level in Admin Center → Permissions Engine, where you define the default permission matrix for each subscription tier.

Full Permission Reference

These are the platform's 22 core feature permissions. Each can be toggled per user or per plan tier.

content.view
View AI-generated content
content.create
Create/generate articles
content.publish
Publish articles to webhook destinations
seo.view
View SEO dashboard
seo.edit
Manage SEO sites and keywords
social.view
View Social Syndicator
social.post
Schedule and publish posts
brand_monitor.view
View Brand Sentinel
brand_monitor.edit
Run audits and scans
voice.view
View Voice AI Studio
voice.create
Create and clone voice agents
automation.view
Access Marketing Automation
crm.view
View Business ERP & CRM
crm.edit
Create invoices and contacts
media.view
View Media Studio
media.generate
Generate images and videos
news.view
View News Factory
news.generate
Generate news content
audiences.view
View Audience/B2B Prospector
audiences.scrape
Run prospect scans
admin.users
Manage platform users (Superadmin)
admin.settings
Access Admin Center (Superadmin)

Multi-Tenant Isolation

BrandedClaws is built as a multi-tenant SaaS platform. Each tenant (subscriber) has their data, configurations, and AI outputs completely isolated from all other tenants:

  • Each user's AI content, articles, media, and CRM contacts are namespaced to their account
  • API keys (voice, telephony, etc.) configured by tenants are encrypted and stored per-account
  • The platform's shared LLM API keys (Gemini, OpenAI, etc.) are set centrally by the Superadmin and shared across tenants — tenants never see these keys
  • Marketing automation funnels use tenant-scoped customer segments
  • Business ERP modules are configured per-tenant with their own company profile

API Key Security

  • Never share your platform API keys — treat them as passwords
  • All API keys stored in BrandedClaws are AES-256 encrypted at rest
  • Keys are transmitted over HTTPS/TLS 1.3 only
  • To rotate a compromised key: update it in the relevant Settings page (Admin Center or your user Settings), then revoke the old key from the external provider's dashboard
  • Session tokens expire after 30 days of inactivity

Superadmin API keys are platform-wide: The LLM, Search, and Voice API keys you enter in Admin Center are used by ALL tenants simultaneously. A compromised key would affect the entire platform. Rotate compromised keys immediately and monitor your provider's usage dashboard for unusual activity.

Two-Factor Authentication (Passkeys + TOTP)

Add a second lock to your account, entirely self-hosted — no SMS codes, no third-party service, no per-login cost. Two-factor authentication is opt-in for all users and mandatory for admin and superadmin roles.

  • Passkeys (recommended): sign in with Face ID, Touch ID, Windows Hello or your device PIN — right after your password, in one tap. Works in the installed PWA and in the browser.
  • Authenticator app (TOTP): scan the standard QR code with any app you already use — Google Authenticator, Authy, 1Password, Bitwarden. Codes refresh every 30 seconds; recently-shown codes still work to tolerate clock drift, but a code can never be used twice.
  • Backup codes: 10 one-time recovery codes generated when you enable 2FA — shown exactly once, download and store them safely. Regenerating invalidates all previous codes.

Enroll: Dashboard → Profile → Security & 2FA. On sign-in, the passkey prompt appears automatically when your device has one; otherwise enter an authenticator or backup code.

Security details worth knowing: TOTP seeds and passkey keys are AES-256-GCM encrypted at rest; enabling, disabling or changing factors signs out all other sessions; sensitive actions (password change, factor removal) require a fresh identity check; wrong second-factor attempts are rate-limited per account AND per IP with escalating lockouts, and every event lands in the audit log. There are no master bypass codes.

Lost-device recovery (admins): Admin Center → User Management → fingerprint icon wipes a user's passkeys, TOTP and backup codes so they re-enroll at next sign-in. It requires the admin's own fresh 2FA verification and is audited. If you are locked out yourself, another administrator performs this for you — keep your backup codes safe.

Troubleshooting

Feature is locked even though my plan should include it
Your Superadmin may have restricted this permission at the user level. Go to Admin Center → User Management and check your individual permission toggles.
User can see features they should not have access to
Check Admin Center → Permissions Engine. A plan tier override or individual grant may be active for that user. Revoke it explicitly.
API key not working after entering it
Verify the key has the correct permissions scope on the provider side (e.g., voice engine key needs read+write). Check for extra spaces when copy-pasting.
Session expired too quickly
Sessions expire after 30 days of inactivity, and are ended immediately when a security change happens on the account (e.g. two-factor factors were changed). Use a strong password and enable 2FA under Profile → Security & 2FA.
Next Guide
LLM Provider & Search Settings
All Guides