# Record-level permissions

{% @arcade/embed flowId="3IjUPM0Jz0BnkPW4XUw0" url="<https://app.arcade.software/share/3IjUPM0Jz0BnkPW4XUw0>" %}

## 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

{% hint style="warning" %}
**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.
{% endhint %}

## 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 ALL of their role's rules
  * If you have 2 rules for the same role, then the filters of Rule 1 and Rule 2 will be joined, so that only the common set of records is accesible to the user with that role
* 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](https://guides.noloco.io/pages/page-visibility-rules) to hide UI elements users can't access
* Provide clear feedback when users encounter restricted content

{% hint style="info" %}
**Remember**: Record-level permissions provide the foundation of secure access control. Combine them with [field-level permissions](https://guides.noloco.io/users-and-permissions/user-roles-and-permissions/field-level-permissions) for comprehensive data security.
{% endhint %}