Roles & Permissions

ZenSearch uses role-based access control (RBAC) to manage what team members can do. Understand the different roles and their capabilities.

Team Roles

ZenSearch has four team-level roles with hierarchical permissions:

Owner

The highest permission level with full control.

Capabilities:

• All Admin permissions
• Delete the team
• Transfer ownership
• Manage billing
• Access all settings

Limitations:

• Every team must have at least one Owner
• Cannot be removed without ownership transfer

Admin

Full management capabilities without team deletion.

Capabilities:

• All Editor permissions
• Invite and remove members
• Change member roles
• Manage all connectors
• Manage all collections
• Configure guardrails
• Manage API keys

Editor

Content creation and connector management.

Capabilities:

• All Viewer permissions
• Create connectors
• Edit connectors they created
• Run sync jobs
• Create collections
• Manage their content

Viewer

Read-only access for consumption.

Capabilities:

• Search and chat
• Use AI agents
• View documents
• View collections
• View activity

Permission Matrix

Action	Owner	Admin	Editor	Viewer
Search & Chat	Yes	Yes	Yes	Yes
Use Agents	Yes	Yes	Yes	Yes
View Documents	Yes	Yes	Yes	Yes
Create Connectors	Yes	Yes	Yes	No
Edit Own Connectors	Yes	Yes	Yes	No
Edit All Connectors	Yes	Yes	No	No
Delete Connectors	Yes	Yes	No	No
Run Sync Jobs	Yes	Yes	Yes	No
Create Collections	Yes	Yes	Yes	No
Edit Collections	Yes	Yes	No	No
Delete Collections	Yes	Yes	No	No
Create Agents	Yes	Yes	Yes	No
Invite Members	Yes	Yes	No	No
Remove Members	Yes	Yes	No	No
Change Roles	Yes	Yes	No	No
Manage API Keys	Yes	Yes	No	No
Configure Guardrails	Yes	Yes	No	No
Manage Billing	Yes	No	No	No
Delete Team	Yes	No	No	No

Document-Level Permissions

Beyond team roles, ZenSearch supports document-level access control.

Permission Types

Type	Description
User	Specific individual access
Group	Team or department access
Team	Entire team access
Domain	Organization-wide access
Public	Anyone can access

Permission Sources

Document permissions can come from:

1. Source Platform: Synced from connected data sources
2. Manual Assignment: Set directly in ZenSearch
3. Team Defaults: Inherited from team settings

Permission Enforcement

Mode	Behavior
Strict	Only show documents user can access in source
Permissive	Show all documents (for internal/trusted use)

Syncing Roles from External Platforms

Beyond document-level permissions, ZenSearch can pull identity and team-role information from your IdP and from connected platforms — keeping ZenSearch role assignments in sync with the rest of your stack so you don't have to maintain a parallel directory.

From your identity provider (OIDC / SAML / Clerk)

Each sign-in is treated as a chance to refresh the user's profile from their identity claims:

• Email is the primary key. Users with a matching email are linked to their existing ZenSearch identity; new emails create a new user.
• Profile fields (name, picture) are synced on every sign-in.
• Org chart claims (manager_email, department, title, job_role) populate the org chart automatically when present. Empty values don't clobber existing data — useful when only some IdP users have manager metadata set.
• Group claims (groups / roles) can be mapped to ZenSearch team roles using the role-mapping rules described below.

From workspace platforms (Slack, Teams, Google Workspace)

When you connect Slack, Microsoft Teams, or Google Workspace as data sources, ZenSearch reads their workspace membership and applies it to document-level permissions in the search index. The mapping tables below show the permission projection for each platform.

Role mapping rules

For self-hosted deployments, you can configure rules that map IdP group names to ZenSearch team roles:

group "zensearch-admins" → Admin in team "Engineering"
group "zensearch-editors" → Editor in team "Engineering"
group everything-else → Viewer

Rules are evaluated on each sign-in. A user removed from an upstream group is downgraded on their next ZenSearch session — there's no manual cleanup step.

Manual override

Anything synced from an external source can be overridden manually in the ZenSearch dashboard. Manual overrides take precedence and are preserved across syncs. Use this for the rare case where IdP groups don't quite match the access model you want.

External Platform Mapping

ZenSearch maps roles from external platforms:

Google Workspace

Google Role	ZenSearch Permission
Owner	Full access
Editor	Read access
Commenter	Read access
Viewer	Read access

Slack

Slack Membership	ZenSearch Permission
Channel member	Read channel content
Non-member	No access

Confluence

Confluence Permission	ZenSearch Permission
Admin	Read access
Can edit	Read access
Can view	Read access
Restricted	No access

Salesforce

Salesforce Sharing	ZenSearch Permission
Owner	Full access
Read/Write	Read access
Read Only	Read access
No access	No access

Best Practices

Role Assignment

1. Least Privilege: Assign minimum necessary role
2. Regular Review: Audit role assignments periodically
3. Clear Ownership: Ensure backup Owners exist
4. Document Decisions: Keep records of role assignments

Permission Management

1. Enable Permission Sync: For sensitive data sources
2. Test Access: Verify users see appropriate content
3. Audit Regularly: Review permission configurations
4. Clear Policies: Document access policies

Troubleshooting

User Can't Access Content

1. Check their team role
2. Verify document-level permissions
3. Confirm permission sync is working
4. Check source platform permissions

Wrong Content Visible

1. Review permission enforcement mode
2. Check document permission settings
3. Verify source permissions are synced
4. Audit permission configuration

Role Change Not Working

1. Verify you have Admin or Owner role
2. Check for role hierarchy restrictions
3. Ensure target role is valid

Next Steps

• Team Members - Manage team membership
• Teams - Work with multiple teams