# User Roles & Permissions

## Why Use Permissions? 🛡

Whether you're building an Internal Tool, a Client Portal or a Partner Portal, it's critical to control who has access to what information.

Permissions let you control **what** your users can see and **how** they can interact with data in your apps. You can use permissions to:

* Limit which pages users can access
* Limit which records a user can read, edit, create or delete
* Hide sensitive fields from certain user types
* Create secure multi-tenant applications

{% hint style="success" %}
**New to permissions?** Start with our [Permissions Quick Start Guide](https://guides.noloco.io/users-and-permissions/permissions-quick-start) for a practical introduction.
{% endhint %}

## Access Control Methods

Noloco provides three complementary approaches to control user access:

| Method                   | Security Level | Purpose            | Configuration      |
| ------------------------ | -------------- | ------------------ | ------------------ |
| **🔒 Permissions**       | High           | Secure data access | Data & API tab     |
| **👁️ Visibility Rules** | Medium         | UI experience      | Build mode         |
| **🔍 Filters**           | Low            | Data organization  | View configuration |

[Learn when to use each approach →](https://guides.noloco.io/users-and-permissions/permissions-vs-visibility-vs-filters)

## Permission Types

### 📊 Record-Level Permissions

Control which records users can access within a table.

**Example**: Sales reps only see accounts in their territory.

[Set up Record-Level Permissions →](https://guides.noloco.io/users-and-permissions/user-roles-and-permissions/record-level-permissions)

### 🏷️ Field-Level Permissions

Control access to specific fields within records.

**Example**: Hide salary information from non-HR staff.

[Set up Field-Level Permissions →](https://guides.noloco.io/users-and-permissions/user-roles-and-permissions/field-level-permissions)

## User Roles

### Built-in Roles

Noloco provides two default roles:

* **Team Admin**: Full access for internal team members
* **User**: Default role for external users (clients, partners)

### Custom Roles

Create additional roles for complex access patterns:

* **Pro plan and above**: Add unlimited custom roles
* **Role-based permissions**: Each role can have different access levels
* **Multiple roles**: Users can have multiple roles (permissions are additive)

## Quick Setup Guide

### 1. Plan Your Access Model

* Identify user types (Admin, Agent, Client, etc.)
* Define what data each type should access
* Determine required security level

### 2. Create User Roles

* Go to **Settings > User Roles**
* Create roles for each user type
* Assign roles to users in the User table

### 3. Configure Permissions

* Navigate to **Data & API tab**
* Set permissions for each sensitive table
* Test with "View as User" feature

### 4. Test and Refine

* Use [Testing as Other Users](https://guides.noloco.io/users-and-permissions/testing-as-other-users)
* Verify security and user experience
* Adjust permissions based on testing

## Permission Configuration Examples

### Example 1: Client Portal Setup 🏢

**Goal**: Clients only see their company's data

**User Roles**:

* Admin (internal)
* Client (external)

**Permissions**:

* **Record-level**: `Company` equals `User's Company`
* **Field-level**: Hide internal pricing and notes from Client role

**Testing**: Use "View as" Client user to verify restricted access

### Example 2: Real Estate Team Access 🏠

**Goal**: Agents only see assigned properties

**User Roles**:

* Manager (full access)
* Agent (limited access)

**Permissions**:

* **Record-level**: `Assigned Agent` equals `Logged in User`
* **Field-level**: Agents can't create properties or edit status

**Testing**: Switch between Manager and Agent views to verify differences

## Advanced Permission Patterns

### Multi-Tenant Applications

* Each tenant's data completely isolated
* User organization determines data access
* Shared resources controlled by admin roles

### Hierarchical Access

* Managers see their team's data + their own
* Multiple permission rules for complex reporting structures
* Inherited permissions from organizational structure

### Progressive Access Levels

* Viewer → Editor → Admin permission progression
* Feature access increases with role level
* Training and onboarding-friendly structure

## Plan Feature Availability

{% hint style="info" %}
**Permissions Plan Requirements**

**All Plans**: Basic permissions and built-in roles

**Pro Plan and Above**:

* Field-level CRUD permissions
* Unlimited custom user roles
* Advanced permission patterns
  {% endhint %}

## Troubleshooting

Having permission issues? Check our comprehensive troubleshooting guide:

[Permissions Troubleshooting Guide →](https://guides.noloco.io/users-and-permissions/permissions-troubleshooting)

### Common Quick Fixes

* **Users can't see records**: Check if permission rules exist for their role
* **Fields still editable**: Verify field-level update permissions
* **Changes not applying**: Test in incognito window and check role assignments

## Best Practices

### Security First

1. **Start restrictive**: Grant minimum necessary access
2. **Test thoroughly**: Use "View as User" extensively
3. **Layer protection**: Combine record and field permissions
4. **Regular audits**: Review permissions as your app evolves

### User Experience

1. **Clear communication**: Users should understand access limitations
2. **Consistent patterns**: Similar roles should have similar access
3. **Graceful degradation**: Provide helpful messages for denied access
4. **Performance consideration**: Complex permissions may impact loading times

### Maintenance

1. **Document decisions**: Keep track of permission logic
2. **Version control**: Test changes before production
3. **User feedback**: Monitor if permissions help or hinder workflows
4. **Simplification**: Consolidate rules when possible

## Related Guides

* [🚀 Permissions Quick Start](https://guides.noloco.io/users-and-permissions/permissions-quick-start) - Get started quickly
* [📊 Record-Level Permissions](https://guides.noloco.io/users-and-permissions/user-roles-and-permissions/record-level-permissions) - Control record access
* [🏷️ Field-Level Permissions](https://guides.noloco.io/users-and-permissions/user-roles-and-permissions/field-level-permissions) - Control field access
* [👥 Testing as Other Users](https://guides.noloco.io/users-and-permissions/testing-as-other-users) - Validate your setup
* [🛠️ Permissions Troubleshooting](https://guides.noloco.io/users-and-permissions/permissions-troubleshooting) - Fix common issues
* [⚖️ Permissions vs Visibility vs Filters](https://guides.noloco.io/users-and-permissions/permissions-vs-visibility-vs-filters) - Choose the right approach

{% hint style="warning" %}
**Remember**: Permissions provide the foundation of secure access control. Always implement proper permissions before relying on visibility rules or filters for any security-sensitive scenarios.
{% endhint %}