Access Control

Access control determines who can do what within your BttrForm organization. From the database level to the user interface, BttrForm enforces access boundaries through multiple layers: role-based permissions, row-level security, API key scopes, session management, and multi-factor authentication. This article explains each layer and how to configure them.

Role Hierarchy

BttrForm uses a four-level role hierarchy. Each role inherits the permissions of the roles below it.

Owner
  └── Admin
        └── Member
              └── Viewer

Permissions by Role

Assigning Roles

1. Navigate to Settings > Team.
2. Click Invite Member to add a new user, or click the role badge next to an existing member to change their role.
3. Select the appropriate role from the dropdown.
4. Changes take effect immediately.

Row-Level Security (RLS)

BttrForm enforces data access at the database level using PostgreSQL Row-Level Security policies. RLS ensures that even if application-level authorization were bypassed, the database itself prevents unauthorized data access.

How RLS Works in BttrForm

Every database query is scoped to the authenticated user's context:

-- Users can only access their own organization's forms
CREATE POLICY "org_member_forms"
  ON public.forms
  FOR ALL
  USING (
    org_id IN (
      SELECT org_id FROM public.memberships
      WHERE user_id = auth.uid()
    )
  );

-- Viewers cannot modify forms
CREATE POLICY "members_can_update_forms"
  ON public.forms
  FOR UPDATE
  USING (
    org_id IN (
      SELECT org_id FROM public.memberships
      WHERE user_id = auth.uid()
      AND role IN ('owner', 'admin', 'member')
    )
  );

What RLS Prevents

• Cross-organization data access -- User A in Organization X cannot query forms belonging to Organization Y, even by manipulating API requests.
• Privilege escalation -- A viewer cannot modify data by sending direct API calls, because the database rejects the write operation.
• Data leakage through joins -- RLS policies apply to all queries, including joins and subqueries, preventing indirect data access.

API Key Scopes

API keys allow programmatic access to BttrForm's REST API. Each key is scoped to limit what operations it can perform.

Available Scopes

Creating API Keys

1. Navigate to Settings > API Keys.
2. Click Create New Key.
3. Enter a descriptive name (e.g., "Analytics Dashboard - Read Only").
4. Select the scope(s) for the key.
5. Set an optional expiration date.
6. Click Create. The key is displayed once -- copy it immediately.

Key Rotation

Regular key rotation reduces the risk of compromised credentials being used long-term.

• Manual rotation -- Create a new key, update your integrations, then revoke the old key.
• Expiration dates -- Set keys to expire after a defined period (30, 60, 90, or 365 days). Expired keys stop working automatically.
• Rotation reminders -- BttrForm sends email notifications 7 days before a key expires.

Key Best Practices

• Use the minimum scope required for each integration. A reporting dashboard needs read, not admin.
• Set expiration dates on all keys. Indefinite keys are a security risk.
• Use separate keys for each integration so that revoking one does not break others.
• Never commit API keys to source control. Use environment variables or a secrets manager.

Session Management

BttrForm provides configurable session management to control how long users stay logged in and under what conditions sessions expire.

Session Settings

Configuring Sessions

1. Navigate to Settings > Security > Session Management.
2. Adjust the settings according to your organization's security requirements.
3. Save. New settings apply to future sessions. Existing sessions continue under the old rules until they expire.

Automatic Session Expiry

When a session expires:

1. The user sees a "Session Expired" message on their next interaction.
2. Unsaved work in the form builder is preserved in local storage and restored after re-login.
3. The user is redirected to the login page.
4. A session expiry event is recorded in the audit log.

Re-authentication

Certain sensitive operations require the user to re-enter their credentials, even during an active session. This protects against unauthorized actions if a device is left unattended.

Operations Requiring Re-authentication

• Exporting form responses
• Changing security or compliance settings
• Managing API keys (create, revoke)
• Modifying billing or subscription settings
• Transferring organization ownership
• Deleting the organization
• Downloading file attachments from HIPAA-enabled forms

How It Works

1. User initiates a sensitive operation.
2. A modal prompts for password entry (or biometric/2FA confirmation).
3. Re-authentication is valid for 5 minutes -- subsequent sensitive operations within this window do not require another prompt.
4. After 5 minutes, the next sensitive operation requires re-authentication again.

Multi-Factor Authentication (MFA)

Multi-factor authentication adds a second verification step beyond the password, significantly reducing the risk of account compromise.

Supported MFA Methods

Enabling MFA

1. Navigate to Settings > Account > Security.
2. Click Enable Two-Factor Authentication.
3. Scan the QR code with your authenticator app.
4. Enter the 6-digit code to verify setup.
5. Save the recovery codes in a secure location.

Enforcing MFA for the Organization

Admins and owners can require MFA for all members:

1. Navigate to Settings > Security > Authentication.
2. Enable Require MFA for all members.
3. Members without MFA will be prompted to set it up on their next login.
4. Members who do not enable MFA within 7 days are locked out until they complete setup.

Audit Trail

Every access control action in BttrForm is logged in the audit trail. This provides a complete record of who did what, when, and from where.

What Is Logged

Viewing the Audit Trail

1. Navigate to Settings > Audit Log.
2. Use filters to narrow by date range, event type, user, or IP address.
3. Click any entry to see full details including the user agent, IP address, and the specific changes made.

Audit Log Integrity

• Audit logs are immutable -- once written, they cannot be modified or deleted by any user.
• Logs are stored separately from application data with their own encryption and access controls.
• Retention is a minimum of 365 days (SOC 2 requirement), configurable up to 7 years on Business and Enterprise plans.