Permissions - Twenty

Twenty’s permission system gives you granular control over who can access and modify data in your workspace. Create custom roles with specific permissions at the object, field, and record level.

Permission model overview

Permissions in Twenty work through a hierarchical system:

Roles

Roles are the foundation of the permission system. Each workspace member is assigned one or more roles that determine their access.

Standard roles

Twenty includes default roles:

Admin: Full access to all data and settings
Member: Standard access to CRM features
Guest: Limited read-only access

Custom roles

Create roles tailored to your organization:

Navigate to Roles

Go to Settings → Workspace → Roles

Create new role

Click “New Role” and configure:

Label: Role name (e.g., “Sales Manager”, “Support Agent”)
Description: What this role is for
Icon: Visual identifier

Configure permissions

Set role-wide permissions:

Can update all settings
Can access all tools
Can read all object records
Can update all object records
Can soft delete all object records
Can destroy all object records

Set object permissions

Define specific permissions per object (covered below).

Role properties

{
  label: "Sales Manager",
  description: "Manages sales team and pipeline",
  icon: "users",
  
  // Global permissions
  canUpdateAllSettings: false,
  canAccessAllTools: true,
  canReadAllObjectRecords: true,
  canUpdateAllObjectRecords: false,
  canSoftDeleteAllObjectRecords: false,
  canDestroyAllObjectRecords: false,
  
  // Assignment options
  canBeAssignedToUsers: true,
  canBeAssignedToAgents: false,
  canBeAssignedToApiKeys: false,
  
  // Editability
  isEditable: true
}

Roles can be assigned to users, AI agents, and API keys, allowing you to control permissions for both human and programmatic access.

Object permissions

Control what actions roles can perform on each object.

CRUD permissions

Four basic permissions for each object:

Create: Can create new records
Read: Can view records
Update: Can modify existing records
Delete: Can soft-delete or permanently remove records

Setting object permissions

Via UI
Via API

Go to Settings → Roles
Select a role
Navigate to “Object Permissions”
For each object, toggle permissions:

Object: Companies
✓ Create
✓ Read
✓ Update
✗ Delete

Object: Opportunities
✓ Create
✓ Read
✓ Update
✓ Delete

mutation UpdateObjectPermission {
  updateObjectPermission(
    roleId: "role-uuid",
    objectId: "object-uuid",
    permissions: {
      canCreate: true,
      canRead: true,
      canUpdate: true,
      canDelete: false
    }
  ) {
    id
    permissions
  }
}

Permission inheritance

Delete permission requires Update permission. You cannot delete records you cannot update.

Permissions have implicit dependencies:

canDelete requires canUpdate
canUpdate requires canRead
Without canRead, the object is invisible to the role

Field permissions

Restrict access to specific fields within objects.

Field visibility

Control which fields roles can see and edit:

Visible: Field appears in views and forms
Editable: Field can be modified
Hidden: Field completely hidden from role

Use cases for field permissions

Sensitive Data
Read-only Fields
Role-specific Fields

Hide confidential information:

Social Security Numbers: Visible only to HR role
Salary information: Visible only to Finance role
API keys: Visible only to Admin role
Credit card info: Never visible to any role

Configuring field permissions

Field Permission Example

// Object: Company
// Role: Sales Rep

Fields:
  name:               { visible: true,  editable: true  }  // Full access
  annualRevenue:      { visible: true,  editable: false }  // Read-only
  internalNotes:      { visible: false, editable: false }  // Hidden
  owner:              { visible: true,  editable: false }  // Read-only
  industry:           { visible: true,  editable: true  }  // Full access

Use field permissions to implement progressive disclosure: show simple fields to all users, advanced fields only to power users.

Row-level permissions

Define which specific records a role can access based on field values.

Permission predicates

Predicates are conditions that determine record visibility:

// Sales reps can only see their own opportunities
{
  field: "ownerId",
  operator: "eq",
  value: "{{currentUser.id}}"
}

Predicate operators

Available operators for row-level predicates:

eq: Equals
ne: Not equals
gt: Greater than
gte: Greater than or equal
lt: Less than
lte: Less than or equal
in: In array
notIn: Not in array
contains: String contains substring
startsWith: String starts with
endsWith: String ends with
isEmpty: Field is null or empty
isNotEmpty: Field has a value

Dynamic predicates

Use variables to make predicates dynamic:

Dynamic Variables

// Current user
{{currentUser.id}}
{{currentUser.email}}
{{currentUser.teamId}}
{{currentUser.role}}

// Related records
{{currentUser.managedTeamIds}}  // Array of team IDs user manages
{{currentUser.regionId}}         // User's assigned region

// Workspace context
{{workspaceId}}

Example row-level permissions

Sales Territory
Team Hierarchy
Customer Portal
Multi-condition

// Sales reps see accounts in their territory
Role: Sales Rep
Object: Company

Predicate:
{
  logicalOperator: "OR",
  predicates: [
    // Accounts they own
    { field: "ownerId", operator: "eq", value: "{{currentUser.id}}" },
    // OR accounts in their territory
    { field: "territory", operator: "eq", value: "{{currentUser.territory}}" }
  ]
}

// Managers see their team's records
Role: Manager
Object: Opportunity

Predicate:
{
  field: "ownerId",
  operator: "in",
  value: "{{currentUser.teamMemberIds}}"
}

// Clients see only their own data
Role: Client
Object: Project

Predicate:
{
  field: "clientCompanyId",
  operator: "eq",
  value: "{{currentUser.companyId}}"
}

// Support sees active tickets in their queue
Role: Support Agent
Object: Ticket

Predicate:
{
  logicalOperator: "AND",
  predicates: [
    {
      // Assigned to them OR unassigned
      logicalOperator: "OR",
      predicates: [
        { field: "assignedTo", operator: "eq", value: "{{currentUser.id}}" },
        { field: "assignedTo", operator: "isEmpty" }
      ]
    },
    // AND not resolved
    { field: "status", operator: "ne", value: "RESOLVED" }
  ]
}

Row-level permissions can impact query performance on large datasets. Use indexed fields in predicates for better performance.

Permission flags

Binary permissions for workspace-level features.

Available permission flags

Flags control access to workspace features:

// Workspace settings
CAN_ACCESS_WORKSPACE_SETTINGS
CAN_EDIT_WORKSPACE_SETTINGS

// Data model
CAN_CREATE_OBJECTS
CAN_EDIT_OBJECTS
CAN_DELETE_OBJECTS
CAN_CREATE_FIELDS
CAN_EDIT_FIELDS
CAN_DELETE_FIELDS

// Workflows
CAN_CREATE_WORKFLOWS
CAN_EDIT_WORKFLOWS
CAN_DELETE_WORKFLOWS
CAN_EXECUTE_WORKFLOWS

// Users and permissions
CAN_INVITE_USERS
CAN_MANAGE_USERS
CAN_MANAGE_ROLES
CAN_ASSIGN_ROLES

// Integrations
CAN_MANAGE_API_KEYS
CAN_MANAGE_WEBHOOKS
CAN_INSTALL_APPS

// Data
CAN_IMPORT_DATA
CAN_EXPORT_DATA
CAN_DELETE_ALL_DATA

Assigning permission flags

Role with Flags

{
  label: "Developer",
  permissionFlags: [
    "CAN_ACCESS_WORKSPACE_SETTINGS",
    "CAN_MANAGE_API_KEYS",
    "CAN_MANAGE_WEBHOOKS",
    "CAN_CREATE_WORKFLOWS",
    "CAN_EDIT_WORKFLOWS",
    "CAN_EXPORT_DATA",
    "CAN_IMPORT_DATA"
  ]
}

Workspace members

Manage who has access to your workspace.

Inviting users

Go to Settings → Members

View all workspace members and pending invitations.

Click Invite Member

Enter email address of person to invite.

Assign role

Choose which role(s) to assign to the new member.

Send invitation

User receives email with link to join workspace.

Member properties

Email: User’s email address
Role(s): Assigned roles (can have multiple)
Status: Active, Invited, Suspended
Locale: User’s language preference
Avatar: Profile picture
Last active: Last login timestamp

Removing access

Go to Settings → Members
Click on user to remove
Choose:
- Suspend: Temporarily disable access (can be restored)
- Remove: Permanently remove from workspace

Removing a user does not delete records they created. Records remain but show “[Deleted User]” as the creator.

Best practices

Role design

Start with broader permissions and tighten as needed. It’s easier to remove permissions than deal with access request tickets.

Create roles by function: “Sales”, “Support”, “Marketing” rather than by seniority
Use least privilege: Give only permissions required for the job
Plan for growth: Design role hierarchy that scales with team size
Document roles: Write clear descriptions of what each role can do

Permission patterns

Sales Team
Support Team

Sales Rep:
- Read: All companies, people, opportunities
- Write: Own opportunities, related tasks
- Row-level: Territory-based or owner-based

Sales Manager:
- Read: All sales data
- Write: Team's opportunities, can reassign
- Row-level: Team hierarchy-based

Sales Ops:
- Read: All data
- Write: Data model, workflows, imports
- Full access to settings

Support Agent:
- Read: Companies, people, tickets
- Write: Tickets, notes, tasks
- Row-level: Assigned tickets + unassigned

Support Manager:
- Read: All support data
- Write: All tickets, can reassign
- Access: Reports and analytics

Support Admin:
- Full access to support objects
- Manage workflows and automation
- Configure integrations

Security considerations

Regular audits: Review permissions quarterly
Offboarding: Remove access immediately when team members leave
API keys: Create roles specifically for API access with minimal permissions
Audit logs: Monitor for unauthorized access attempts
Sensitive data: Use field permissions for PII and financial data

Performance optimization

Simple predicates: Complex row-level rules slow down queries
Indexed fields: Use indexed fields in row-level predicates
Cache roles: Permissions are cached, changes take effect on next login
Limit roles: Keep role count manageable (< 20 roles)

Testing permissions

Create test user

Invite a test account with the role you want to verify.

Use an incognito browser to log in with test account.

Verify visibility

Check that objects, fields, and records are visible/hidden correctly.

Test actions

Attempt to create, update, and delete records to verify permissions.

Check edge cases

Test row-level predicates with different data scenarios.

Admins can use “View as” feature to preview the workspace as different roles without logging out.

Troubleshooting

User can’t see data they should access

Check object permissions: Is Read enabled?
Check field permissions: Are fields visible?
Check row-level predicates: Do predicates match user’s context?
Check user’s role assignments: Is role actually assigned?
Clear cache and refresh: Log out and back in

User can access data they shouldn’t

Review all assigned roles: User may have multiple roles
Check for permissive row-level rules: OR conditions may be too broad
Audit permission flags: May have elevated workspace permissions
Review role inheritance: Check if roles grant unexpected access

Performance issues with permissions

Simplify row-level predicates: Reduce nested conditions
Index predicate fields: Add database indexes to filtered fields
Limit role count: Consolidate similar roles
Cache optimization: Adjust cache TTL for permission checks

Next steps

Objects and fields

Understand what data permissions control

Workflows

Automate role-based actions and notifications

API authentication

Use API keys with role-based permissions

Workspace Settings

Configure workspace permissions and roles

Get Started

Core Concepts

​Permission model overview

​Roles

​Standard roles

​Custom roles

​Role properties

​Object permissions

​CRUD permissions

​Setting object permissions

​Permission inheritance

​Field permissions

​Field visibility

​Use cases for field permissions

​Configuring field permissions

​Row-level permissions

​Permission predicates

​Predicate operators

​Dynamic predicates

​Example row-level permissions

​Permission flags

​Available permission flags

​Assigning permission flags

​Workspace members

​Inviting users

​Member properties

​Removing access

​Best practices

​Role design

​Permission patterns

​Security considerations

​Performance optimization

​Testing permissions

​Troubleshooting

​User can’t see data they should access

​User can access data they shouldn’t

​Performance issues with permissions

​Next steps

Objects and fields

Workflows

API authentication

Workspace Settings

Build docs developers (and LLMs) love

Permission model overview

Roles

Standard roles

Custom roles

Role properties

Object permissions

CRUD permissions

Setting object permissions

Permission inheritance

Field permissions

Field visibility

Use cases for field permissions

Configuring field permissions

Row-level permissions

Permission predicates

Predicate operators

Dynamic predicates

Example row-level permissions

Permission flags

Available permission flags

Assigning permission flags

Workspace members

Inviting users

Member properties

Removing access

Best practices

Role design

Permission patterns

Security considerations

Performance optimization

Testing permissions

Troubleshooting

User can’t see data they should access

User can access data they shouldn’t

Performance issues with permissions

Next steps