Role-Based Access Control

Set up roles and permissions to control who can access and modify data in your Cocobase project.

All role and permission configurations are managed through the Cocobase Dashboard. No code changes required.

Overview

Cocobase RBAC features:

Predefined roles - Admin, Editor, Viewer, and custom roles
Collection-level permissions - Control access per collection
Field-level permissions - Hide sensitive fields from specific roles
User assignment - Assign roles to users in the dashboard
API enforcement - Permissions automatically enforced by SDKs
Custom roles - Create unlimited custom roles

Default Roles

Cocobase comes with three predefined roles:

Admin

Full access to everything:

✅ Create, read, update, delete all documents
✅ Access all collections
✅ Manage users and roles
✅ Configure project settings
✅ View analytics and logs

Editor

Can manage content but not configuration:

✅ Create, read, update, delete documents
✅ Access assigned collections
❌ Cannot manage users or roles
❌ Cannot change project settings
✅ View basic analytics

Viewer

Read-only access:

❌ Cannot create, update, or delete
✅ Read documents
✅ Access assigned collections
❌ Cannot manage users
❌ Cannot change settings

Setting Up Roles

Step 1: Access Role Management

Log in to Cocobase Dashboard
Select your project
Navigate to Settings → Roles & Permissions
View existing roles and permissions

Step 2: Create Custom Role

Click Create Role
Enter role details:
- Name: e.g., “Content Manager”, “Customer Support”
- Description: What this role can do
- Role Key: Lowercase identifier (e.g., “content_manager”)
Click Create

Step 3: Configure Permissions

For each collection, set permissions:

Collection Access

Permission	Description
No Access	Cannot see collection at all
Read Only	Can view documents
Read & Write	Can create and edit documents
Full Access	Can create, edit, and delete documents

Document Ownership

Own Documents Only: Users can only access documents they created
All Documents: Users can access any document in the collection
Filtered Access: Custom filters based on document fields

Field-Level Permissions

Hide sensitive fields from specific roles:

Select collection
Click Field Permissions
For each field, choose visibility:
- Visible: Field is included in responses
- Hidden: Field is excluded from responses
- Write Only: Can set but not read (e.g., passwords)

Step 4: Assign Roles to Users

Go to Users in the dashboard
Select a user
Click Assign Role
Choose role(s)
Save changes

Users can have multiple roles. Permissions are combined (most permissive wins).

Permission Examples

Example 1: Blog Platform

Roles:

Admin: Full access
Author: Can create and edit own posts
Moderator: Can edit any post, manage comments
Reader: Read-only access to published posts

Configuration:

Collection	Admin	Author	Moderator	Reader
posts	Full Access	Own Documents (Read/Write)	All Documents (Read/Write)	Read Only (status=published)
comments	Full Access	Own Documents (Read/Write)	All Documents (Full Access)	Read Only
users	Full Access	Own Profile Only	Read Only	No Access
categories	Full Access	Read Only	Read Only	Read Only

Example 2: E-commerce Store

Roles:

Admin: Full access to everything
Store Manager: Manage products, orders, inventory
Customer Support: View orders, update order status, manage customer inquiries
Customer: View products, manage own orders and profile

Configuration:

Collection	Admin	Store Manager	Support	Customer
products	Full Access	Full Access	Read Only	Read Only
orders	Full Access	Full Access	Read & Update (own)	Own Documents (Read Only)
customers	Full Access	Read Only	Read & Update	Own Profile Only
inventory	Full Access	Read & Write	No Access	No Access
payments	Full Access	No Access	No Access	Own Documents (Read Only)

Field Visibility: Orders collection:

Customer role cannot see: cost_price, supplier_id, profit_margin
Support role cannot see: cost_price, profit_margin

Example 3: SaaS Application

Roles:

Workspace Owner: Full access to workspace data
Workspace Admin: Manage team members, most data
Team Member: Access assigned projects
Guest: Limited read-only access

Configuration:

Collection	Owner	Admin	Member	Guest
projects	Full Access	Full Access	Assigned Projects	Assigned Projects (Read Only)
tasks	Full Access	Full Access	Assigned Tasks	Assigned Tasks (Read Only)
team_members	Full Access	Read & Write	Read Only	Read Only
billing	Full Access	Read Only	No Access	No Access
api_keys	Full Access	No Access	No Access	No Access

Using Roles in Your Application

Check User Role

JavaScript
TypeScript
Dart
Python

import { Cocobase } from 'cocobase';

const db = new Cocobase({ apiKey: 'your-api-key' });

// Get current user with role
const user = await db.auth.getUser();
console.log('User role:', user.role);

// Check if user has specific role
if (db.auth.hasRole('admin')) {
  // Show admin features
}

// Check multiple roles
if (db.auth.hasRole('admin') || db.auth.hasRole('editor')) {
  // Show content management features
}

import { Cocobase } from 'cocobase';

const db = new Cocobase({ apiKey: 'your-api-key' });

interface User {
  id: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer' | 'custom';
  roles?: string[]; // If multiple roles
}

const user = await db.auth.getUser() as User;

// Type-safe role check
const isAdmin = db.auth.hasRole('admin');
const canEdit = db.auth.hasRole('admin') || db.auth.hasRole('editor');

import 'package:cocobase_flutter/cocobase_flutter.dart';

final db = Cocobase(CocobaseConfig(apiKey: 'your-api-key'));

// Get user role
final user = await db.auth.getUser();
print('User role: ${user.role}');

// Check role
if (user.role == 'admin') {
  // Show admin UI
}

// Check multiple roles
final canManageContent = ['admin', 'editor'].contains(user.role);

from cocobase import Cocobase

db = Cocobase(api_key='your-api-key')

# Get user role
user = db.auth.get_user()
print(f"User role: {user['role']}")

# Check role
if user['role'] == 'admin':
    # Admin functionality
    pass

# Check multiple roles
can_edit = user['role'] in ['admin', 'editor']

Permissions Are Enforced Automatically

The SDK automatically enforces permissions based on the authenticated user’s role:

// User with "viewer" role
const db = new Cocobase({ apiKey: 'your-api-key' });
await db.auth.login({ email: 'viewer@example.com', password: 'password' });

// This works - viewers can read
const posts = await db.listDocuments('posts');

// This fails - viewers cannot write
try {
  await db.createDocument('posts', { title: 'New Post' });
} catch (error) {
  console.error('Permission denied:', error.message);
  // Error: Insufficient permissions. Required: write. Current role: viewer
}

Role-Based UI

Show/hide UI elements based on user role:

import React, { useEffect, useState } from 'react';
import { Cocobase } from 'cocobase';

const db = new Cocobase({ apiKey: 'your-api-key' });

function Dashboard() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    async function fetchUser() {
      const currentUser = await db.auth.getUser();
      setUser(currentUser);
    }
    fetchUser();
  }, []);

  if (!user) return <div>Loading...</div>;

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Welcome, {user.email}!</p>

      {/* Show for all authenticated users */}
      <div>
        <h2>Your Content</h2>
        {/* List user's documents */}
      </div>

      {/* Show only for editors and admins */}
      {(db.auth.hasRole('admin') || db.auth.hasRole('editor')) && (
        <div>
          <h2>Content Management</h2>
          <button>Create New Post</button>
          <button>Edit Posts</button>
        </div>
      )}

      {/* Show only for admins */}
      {db.auth.hasRole('admin') && (
        <div>
          <h2>Admin Panel</h2>
          <button>Manage Users</button>
          <button>View Analytics</button>
          <button>Project Settings</button>
        </div>
      )}
    </div>
  );
}

Document Ownership

Configure who can access documents based on ownership.

Setting Document Owner

Documents automatically track the creator:

// User creates a document
await db.auth.login({ email: 'user@example.com', password: 'password' });

const post = await db.createDocument('posts', {
  title: 'My Post',
  content: 'Hello world'
});

// Document automatically includes:
// {
//   id: '...',
//   createdBy: 'user-id',
//   data: { title: 'My Post', content: 'Hello world' }
// }

Own Documents Permission

In the dashboard, set collection permission to Own Documents Only:

Settings → Roles & Permissions
Select role (e.g., “Author”)
For “posts” collection, choose Own Documents Only
Save

Now users with “Author” role can only access documents they created:

// Author user logs in
await db.auth.login({ email: 'author@example.com', password: 'password' });

// Can see only their own posts
const myPosts = await db.listDocuments('posts');
// Returns only posts where createdBy === current user ID

// Cannot access other users' posts
try {
  await db.getDocument('posts', 'someone-elses-post-id');
} catch (error) {
  // Error: Document not found (or permission denied)
}

Custom Permission Filters

Create advanced permission rules using custom filters.

Dashboard Configuration

Settings → Roles & Permissions
Select role
For collection, choose Custom Filter
Define filter rules:

Example: Users can only see documents from their organization

{
  "organizationId": "{user.organizationId}"
}

Example: Users can see published documents or their own drafts

{
  "$or": [
    { "status": "published" },
    { "createdBy": "{user.id}", "status": "draft" }
  ]
}

Example: Regional managers see documents from their region

{
  "region": "{user.region}"
}

Variables Available

{user.id} - Current user’s ID
{user.email} - Current user’s email
{user.role} - Current user’s role
{user.*} - Any custom user field

Best Practices

Use Least Privilege Principle

Give users the minimum permissions needed:

Start with most restrictive role
Add permissions as needed
Regularly audit role assignments
Remove unnecessary permissions

Create Role Hierarchy

Organize roles from most to least privileged:

Owner / Super Admin
Admin
Manager
Editor / Contributor
Viewer / Guest

Higher roles inherit lower role permissions.

Document Your Roles

Maintain clear documentation:

## Role Definitions

### Admin
- Can manage users and settings
- Full access to all collections
- Assigned to: Core team members

### Content Manager
- Can create and edit all content
- Cannot delete or manage users
- Assigned to: Content team

### Viewer
- Read-only access to public content
- Cannot modify anything
- Assigned to: Clients, stakeholders

Test Permission Changes

Before deploying role changes:

Create test users for each role
Test all CRUD operations
Verify field visibility
Test edge cases
Document expected behavior

Handle Permission Errors Gracefully

try {
  await db.createDocument('posts', data);
} catch (error) {
  if (error.code === 'PERMISSION_DENIED') {
    alert('You do not have permission to create posts. Please contact your administrator.');
  } else {
    alert('An error occurred. Please try again.');
  }
}

Troubleshooting

User Cannot Access Collection

Problem: User gets “Permission Denied” error Solutions:

Check user’s role assignment in dashboard
Verify role has permission for that collection
Check custom filters aren’t blocking access
Ensure user is authenticated

Field Not Appearing in Response

Problem: Expected field is missing from document Solutions:

Check field-level permissions for user’s role
Verify field exists in document
Check if field is marked as “Hidden” for this role

User Can Access Too Much

Problem: User can see data they shouldn’t Solutions:

Review role permissions
Enable “Own Documents Only” if appropriate
Add custom permission filters
Verify role assignment is correct

Permission Changes Not Applied

Problem: Role changes don’t take effect Solutions:

User needs to log out and log back in
Clear SDK cache: db.auth.refreshToken()
Wait a few seconds for propagation
Check dashboard for save confirmation

Next Steps

Authentication

Learn about user authentication

Email Integration

Set up email templates and notifications

Migrations

Import data from other databases

Best Practices

Security and optimization tips

​Role-Based Access Control

​Overview

​Default Roles

​Admin

​Editor

​Viewer

​Setting Up Roles

​Step 1: Access Role Management

​Step 2: Create Custom Role

​Step 3: Configure Permissions

​Collection Access

​Document Ownership

​Field-Level Permissions

​Step 4: Assign Roles to Users

​Permission Examples

​Example 1: Blog Platform

​Example 2: E-commerce Store

​Example 3: SaaS Application

​Using Roles in Your Application

​Check User Role

​Permissions Are Enforced Automatically

​Role-Based UI

​Document Ownership

​Setting Document Owner

​Own Documents Permission

​Custom Permission Filters

​Dashboard Configuration

​Variables Available

​Best Practices

​Troubleshooting

​User Cannot Access Collection

​Field Not Appearing in Response

​User Can Access Too Much

​Permission Changes Not Applied

​Next Steps

Authentication

Email Integration

Migrations

Best Practices

Role-Based Access Control

Overview

Default Roles

Admin

Editor

Viewer

Setting Up Roles

Step 1: Access Role Management

Step 2: Create Custom Role

Step 3: Configure Permissions

Collection Access

Document Ownership

Field-Level Permissions

Step 4: Assign Roles to Users

Permission Examples

Example 1: Blog Platform

Example 2: E-commerce Store

Example 3: SaaS Application

Using Roles in Your Application

Check User Role

Permissions Are Enforced Automatically

Role-Based UI

Document Ownership

Setting Document Owner

Own Documents Permission

Custom Permission Filters

Dashboard Configuration

Variables Available

Best Practices

Troubleshooting

User Cannot Access Collection

Field Not Appearing in Response

User Can Access Too Much

Permission Changes Not Applied

Next Steps