Record-level permissions

Control user access with record-level permission rules

What are Record-Level Permissions?

Record-level permissions control which specific records users can access within a table. Unlike UI-level filters, these permissions work at the database/API level, making them much more secure.

Key Benefits:

• API-Level Security: Data restrictions apply even when accessed through APIs

• Role-Based Access: Different user roles can have different record access

• Relationship-Based Filtering: Restrict access based on record relationships

• Complete Data Protection: Unauthorized records never reach the user's device

Security Note: While filters at the UI level can manage what users see, database-level permission rules are much more secure as they ensure restricted data never reaches the app, protecting sensitive information effectively.

When to Use Record-Level Permissions

Use record-level permissions when:

• Users should only see records they're assigned to or own

• Different user types need access to different subsets of data

• You need secure, API-level data protection

• Building multi-tenant applications

• Handling sensitive or confidential information

Example Scenarios:

• Real estate agents only seeing their assigned properties

• Sales reps only accessing their client accounts

• Project managers only viewing projects they lead

• Students only seeing their own courses and grades

Step-by-Step Setup Guide

Prerequisites

Before setting up record-level permissions, ensure your data model supports the required relationships:

1. User Relationships: Your target table must have a relationship field linking to the Noloco User table or a related user table

2. Proper User Roles: Users must be assigned appropriate roles in their user records

3. Data Structure: The relationship between users and records must be clearly defined

Example Setup: In a real estate CRM, each property record has an "assigned agent" field that links to the agents table, which is connected to the Noloco User table.

Configuration Steps

Step 1: Navigate to Table Permissions

1. Go to the Data & API tab in your app builder

2. Hover over the table you want to secure (e.g., "Properties")

3. Click the permissions icon 🛡️

4. If permissions aren't enabled, toggle them on (this creates a default rule)

Step 2: Create a New Permission Rule

1. Click "+ New" to add a new permission rule

2. Name your rule descriptively (e.g., "Agent Property Permissions")

3. Select the user role this rule applies to (e.g., "Agent")

Step 3: Configure Record Access

1. Disable "All Records" toggle - by default, new rules allow access to all records

2. Add access condition by clicking "Add Condition"

3. Set the relationship filter:

   • Choose the field that links records to users (e.g., "Assigned Agent")

   • Select "equals"

   • Choose "Logged in User" from the dropdown

4. Configure CRUD permissions (Create, Read, Update, Delete) as needed

5. Click Save to apply the rule

Testing Your Permissions

After setting up permissions, always test to ensure they work correctly:

1. Use "View as User" feature:

   • Look for the "👥" icon in the build toolbar

   • Select a user with the role you've configured

   • Navigate through the app to verify record access

2. Verify expected behavior:

   • Users should only see records they have access to

   • Restricted records should not appear in lists or searches

   • Direct navigation to restricted records should be blocked

Example: When testing as "Gal Samurai" (an agent), the properties list should only show properties assigned to her, and she shouldn't be able to access other agents' properties.

Common Permission Patterns

Pattern 1: User-Owned Records

Use Case: Users can only access records they created or own Setup: Link records to user via "Created By" or "Owner" field Condition: Owner equals Logged in User

Pattern 2: Team-Based Access

Use Case: Users access records based on team membership Setup: Link records to teams, and users to teams Condition: Team equals User's Team (via lookup)

Pattern 3: Hierarchical Access

Use Case: Managers see their team's records + their own Setup: Multiple permission rules for same role Conditions:

• Rule 1: Owner equals Logged in User

• Rule 2: Team Lead equals Logged in User

Pattern 4: Client Portal Access

Use Case: Clients only see records related to their company Setup: Link records to companies, users to companies Condition: Company equals User's Company

Troubleshooting Common Issues

Users Can't See Any Records

Cause: Permission rule is too restrictive or missing required relationships

Solutions:

1. Check if the user has the expected role assigned

2. Verify the relationship field exists and is properly populated

3. Ensure the permission condition matches your data structure

4. Test with "View as User" to debug the specific issue

Permission Rules Not Working

Cause: Common configuration errors

Solutions:

1. Verify relationships: Ensure the linking field connects to the right table

2. Check user roles: Confirm users have the role the rule applies to

3. Review conditions: Make sure permission conditions match your data model

4. Test systematically: Use "View as User" with different user roles

Conflicting Permission Rules

Cause: Multiple rules for the same role creating unexpected access patterns

Understanding Rule Logic:

• Permission rules are additive for the same role

• Users get access to records that match ANY of their role's rules

• Field permissions combine (if any rule grants access, user gets that permission)

Best Practices

Security Best Practices

• Always use record-level permissions for sensitive data

• Test permissions thoroughly before deploying to production

• Regularly review permission rules as your app evolves

• Use the principle of least privilege (grant minimum necessary access)

Performance Considerations

• Simple relationship conditions perform better than complex filters

• Index fields used in permission conditions for better performance

• Monitor query performance with complex permission setups

User Experience

• Combine permissions with clear error messages when access is denied

• Use visibility rules to hide UI elements users can't access

• Provide clear feedback when users encounter restricted content

Remember: Record-level permissions provide the foundation of secure access control. Combine them with field-level permissions for comprehensive data security.