# 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](/users-and-permissions/permissions-quick-start.md) 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 →](/users-and-permissions/permissions-vs-visibility-vs-filters.md)

## 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 →](/users-and-permissions/user-roles-and-permissions/record-level-permissions.md)

### 🏷️ Field-Level Permissions

Control access to specific fields within records.

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

[Set up Field-Level Permissions →](/users-and-permissions/user-roles-and-permissions/field-level-permissions.md)

## 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](/users-and-permissions/testing-as-other-users.md)
* 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 →](/users-and-permissions/permissions-troubleshooting.md)

### 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](/users-and-permissions/permissions-quick-start.md) - Get started quickly
* [📊 Record-Level Permissions](/users-and-permissions/user-roles-and-permissions/record-level-permissions.md) - Control record access
* [🏷️ Field-Level Permissions](/users-and-permissions/user-roles-and-permissions/field-level-permissions.md) - Control field access
* [👥 Testing as Other Users](/users-and-permissions/testing-as-other-users.md) - Validate your setup
* [🛠️ Permissions Troubleshooting](/users-and-permissions/permissions-troubleshooting.md) - Fix common issues
* [⚖️ Permissions vs Visibility vs Filters](/users-and-permissions/permissions-vs-visibility-vs-filters.md) - 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guides.noloco.io/users-and-permissions/user-roles-and-permissions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.