snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/user-guide/permissions-access/capabilities/permissions.mdx

@@ -0,0 +1,207 @@
+---
+title: Permissions
+description: Control access to objects, fields, and settings with role-based permissions.
+---
+
+Twenty's permission system allows you to control access to three main areas:
+- **Objects and Fields**: Control who can view, edit, or delete records and individual fields
+- **Settings**: Manage access to workspace configuration and administrative functions
+- **Actions**: Control general workspace actions like importing data or sending emails
+
+## Create a Role
+
+To create a new role:
+
+1. Go to **Settings → Members → Roles**
+2. Under **All Roles**, click on **+ Create Role**
+3. Enter a role name
+4. In the default **Permissions** tab, [configure permissions](#customize-permissions)
+5. Click **Save** to finish
+
+## Delete a Role
+
+To delete a role:
+
+1. Go to **Settings → Members → Roles**
+2. Click on the role you want to remove
+3. Open the **Settings** tab, then click **Delete Role**
+4. Click **Confirm** in the modal
+
+<Note>
+If a role is deleted, any workspace member assigned to it will be automatically reassigned to the default role. All roles except the **Admin** role can be deleted. There must always be at least one member assigned to the **Admin** role.
+</Note>
+
+## Assign Roles to Members
+
+### View Current Assignments
+- Go to **Settings → Members → Roles**
+- See all roles and how many members are assigned to each
+- View which members have which roles
+
+### Assign a Role to a Member
+1. Go to **Settings → Members → Roles**
+2. Click on the role you want to assign
+3. Open the **Assignment** tab
+4. Click **+ Assign to member**
+5. Select the workspace member from the list
+6. Confirm the assignment
+
+### Set Default Role
+1. Go to **Settings → Members → Roles**
+2. In the **Options** section, find **Default Role**
+3. Select which role new members should automatically receive
+4. New workspace members will be assigned this role when they join
+
+<Note>
+You can only assign roles to existing workspace members. To invite new members, use [Member Management](/user-guide/settings/capabilities/member-management).
+</Note>
+
+## Customize Permissions
+
+Permissions determine what each role can access or modify within your workspace, including workspace objects, records, settings, and actions.
+
+### Object Permissions
+
+The **Objects** section controls what this role can do with records across your workspace.
+
+#### Set Default Permissions (All Objects)
+
+First, configure the baseline permissions that apply to **all objects** by default:
+
+| Permission | Description |
+|------------|-------------|
+| **See Records on All Objects** | View records in lists and detail pages |
+| **Edit Records on All Objects** | Modify existing records |
+| **Delete Records on All Objects** | Soft-delete records (can be restored) |
+| **Destroy Records on All Objects** | Permanently delete records |
+
+Select or unselect based on what should be the default behavior for this role.
+
+<Note>
+**Example — Intern role**: An intern should be able to see all objects but not edit them by default. Enable "See Records on All Objects" but leave "Edit Records on All Objects" unchecked.
+</Note>
+
+#### Add Object-Level Exceptions
+
+After setting defaults, use the **Object-Level** sub-section to add rules that override the defaults for specific objects.
+
+Click **+ Add rule** and select an object to create an exception.
+
+**Example rules for an Intern role:**
+
+| Rule | Effect |
+|------|--------|
+| Opportunities → disable "See Records" | Intern cannot see the Opportunities object at all |
+| People → enable "Edit Records" | Intern can edit People records (but not other objects) |
+
+### Row-Level Permissions
+
+<Note>
+Row-level permissions are a **Premium feature** available on the **Organization** plan (Cloud and Self-Hosted).
+</Note>
+
+Row-level permissions let you restrict which individual records a role can see or edit, based on dynamic criteria. Unlike object permissions (which apply to an entire object type), row-level permissions evaluate each record independently.
+
+**Example use cases:**
+- Sales reps can only see their own opportunities
+- Managers can see all records in their region
+- Support agents can only view tickets assigned to them
+
+To configure row-level permissions, open a role, navigate to the **Objects** tab, and use the **Row-Level** section to define filter conditions for a specific object.
+
+### Field Permissions
+
+Within each object-level rule, you can go further and configure **field-level permissions** to control access to specific fields.
+
+| Permission | Description |
+|------------|-------------|
+| **See Field** | View the field value |
+| **Edit Field** | Modify the field value |
+| **No Access** | Field is completely hidden |
+
+**Example — Restrict sensitive fields:**
+
+For the Intern role with People edit access, you might want to restrict certain fields:
+- People → Email → **See Field** only (cannot edit)
+- People → Address → **No Access** (completely hidden)
+
+This allows the intern to edit most People fields while protecting sensitive information.
+
+### How Permission Inheritance Works
+
+Permissions cascade from general to specific:
+
+1. **All Objects** → sets the baseline for all objects
+2. **Object-Level rules** → override the baseline for specific objects
+3. **Field-Level rules** → override the object setting for specific fields
+
+More specific settings always take precedence.
+
+### Managing Permission Overrides
+
+To override inherited permissions:
+
+1. Click **X** to remove the inherited rule
+2. Select the specific permissions you want
+3. Click the orange **Undo** icon (circular arrow) to revert changes
+
+When done, click **Finish**, then **Save** once redirected to the role page.
+
+### Workspace Settings Permissions
+
+Control access to workspace settings in two ways:
+
+- Toggle **Settings All Access** to grant full access
+- Or enable specific permissions (e.g., API key generation, workspace preferences, role assignment, data model configuration, security settings, and workflow management)
+
+<Note>
+**Current limitation**: Access to workflow management is currently required to manually trigger workflows. This behavior may change in future releases.
+</Note>
+
+### Workspace Action Permissions
+
+Control access to general workspace actions:
+
+- Toggle **Application All Access** to grant full permissions
+- Or enable individual actions such as **Send Email**, **Import CSV**, and **Export CSV**
+
+## Assign Roles to API Keys and AI Agents
+
+Beyond workspace members, roles can also be assigned to **API Keys** and **AI Agents**. This is particularly helpful for teams who want to control exactly "who" can do what in their workspace—including automated processes and integrations.
+
+### Why Assign Roles to API Keys and AI Agents?
+
+- **Security**: Limit what automated processes can access or modify
+- **Compliance**: Ensure integrations only touch the data they need
+- **Control**: Prevent accidental data changes from misconfigured automations
+- **Auditability**: Track which actions were performed by which integration or agent
+
+### Assign a Role to an API Key
+
+1. Go to **Settings → Members → Roles**
+2. Click on the role you want to assign
+3. Open the **Assignment** tab
+4. Under **API Keys**, click **+ Assign to API key**
+5. Select the API key from the list
+6. Confirm the assignment
+
+The API key will now inherit all permissions defined by that role. Any API calls made with this key will be restricted accordingly.
+
+<Note>
+API keys without an assigned role use default permissions. For tighter security, always assign a specific role to production API keys.
+</Note>
+
+### Assign a Role to an AI Agent
+
+1. Go to **Settings → Members → Roles**
+2. Click on the role you want to assign
+3. Open the **Assignment** tab
+4. Under **AI Agents**, click **+ Assign to AI agent**
+5. Select the AI agent from the list
+6. Confirm the assignment
+
+The AI agent will only be able to access data and perform actions allowed by its assigned role.
+
+<Note>
+For AI agents running within workflows, this ensures the agent cannot access or modify data outside its intended scope—even if the workflow has broader permissions.
+</Note>

packages/twenty-docs/user-guide/permissions-access/capabilities/sso-configuration.mdx

@@ -0,0 +1,105 @@
+---
+title: SSO Configuration
+description: Configure Single Sign-On for secure enterprise authentication.
+---
+
+## About SSO
+
+Single Sign-On (SSO) allows your team members to log into Twenty using your organization's identity provider. This provides:
+- **Centralized access control**: Manage access from one place
+- **Enhanced security**: Leverage your existing security policies
+- **Better user experience**: One set of credentials for all tools
+
+## Supported Providers
+
+Twenty supports SSO with:
+- **SAML 2.0**: Works with most enterprise identity providers
+- **Google Workspace**: For organizations using Google
+- **Microsoft Entra ID** (formerly Azure AD): For Microsoft environments
+
+## Setting Up SSO
+
+### Prerequisites
+- Organization plan (cloud and self-hosted workspaces)
+- Admin access to your identity provider
+- Admin access to your Twenty workspace
+
+### Configuration Steps
+
+#### 1. Access SSO Settings
+1. Go to **Settings → Security**
+2. Find the **SSO Configuration** section
+3. Click **Configure SSO**
+
+#### 2. Choose Your Provider
+Select your identity provider from the list or choose "Custom SAML" for other providers.
+
+#### 3. Configure Your Identity Provider
+You'll need to configure your identity provider with:
+- **Entity ID**: Provided by Twenty
+- **ACS URL**: The callback URL for authentication
+- **Certificate**: For secure communication
+
+#### 4. Enter Provider Details in Twenty
+- **SSO URL**: Login URL from your provider
+- **Entity ID**: Your provider's identifier
+- **Certificate**: X.509 certificate from your provider
+
+#### 5. Test and Enable
+1. Click **Test Configuration** to verify setup
+2. Enable SSO when testing is successful
+3. Configure user provisioning preferences
+
+## User Provisioning
+
+### Just-in-Time (JIT) Provisioning
+- Users are created automatically on first login
+- Users are assigned a default role automatically
+- No manual user creation needed
+
+### Manual Provisioning
+- Invite users before they can log in
+- Pre-assign specific roles
+- More control over who can access the workspace
+
+## Managing SSO Users
+
+### Role Assignment
+SSO users can be assigned roles like regular users:
+1. Go to **Settings → Members**
+2. Find the user
+3. Change their role as needed
+
+### Access Revocation
+To remove access for SSO users:
+- Remove them from your identity provider, or
+- Remove them from the Twenty workspace
+
+## Best Practices
+
+### Security
+- **Require SSO**: Disable password login for SSO users
+- **Regular audits**: Review access periodically
+- **Strong IdP policies**: Enforce MFA at the identity provider
+
+### User Management
+- **Clear naming**: Use consistent naming from your directory
+- **Group mapping**: Map IdP groups to Twenty roles (if available)
+- **Offboarding process**: Include Twenty in your deprovisioning workflow
+
+## Troubleshooting
+
+### Common Issues
+- **Certificate errors**: Ensure the certificate hasn't expired
+- **URL mismatches**: Verify the ACS URL matches exactly
+- **User not found**: Check JIT provisioning settings
+
+### Getting Help
+If you encounter issues, contact support with:
+- Error messages received
+- Identity provider being used
+- Configuration details (without sensitive data)
+
+<Tip>
+Need SSO configured for your organization? [Find a certified Twenty partner](https://twenty.com/partners/list?categories=SOLUTIONING&ref=docs-sso) who specializes in SSO and identity setup. *(Prefer to loop in Twenty directly? [contact@twenty.com](mailto:contact@twenty.com))*
+</Tip>

packages/twenty-docs/user-guide/permissions-access/how-tos/permissions-faq.mdx

@@ -0,0 +1,121 @@
+---
+title: Permissions FAQ
+description: Frequently asked questions about roles and permissions.
+---
+
+## Roles
+
+<AccordionGroup>
+<Accordion title="What roles come with Twenty by default?">
+Twenty comes with **Admin** and **Member** roles by default. You can create additional custom roles based on your team's needs (e.g., Sales Rep, Manager, Read-Only User).
+</Accordion>
+
+<Accordion title="Can I delete the Admin role?">
+No, the Admin role cannot be deleted. There must always be at least one member assigned to the Admin role.
+</Accordion>
+
+<Accordion title="What happens when I delete a role?">
+Any workspace member assigned to that role will be automatically reassigned to the default role.
+</Accordion>
+
+<Accordion title="How do I set a default role for new members?">
+Go to **Settings → Members → Roles**, find the **Default Role** option, and select which role new members should automatically receive when they join.
+</Accordion>
+
+<Accordion title="Can I assign multiple roles to one user?">
+No, each user can only have one role at a time. Create a custom role if you need a combination of permissions.
+</Accordion>
+</AccordionGroup>
+
+## Permissions
+
+<AccordionGroup>
+<Accordion title="What's the difference between object and field permissions?">
+- **Object permissions**: Control access to entire records (e.g., can see/edit/delete People records)
+- **Field permissions**: Control access to specific fields within an object (e.g., can see but not edit the Salary field)
+
+Field permissions allow more granular control over sensitive data.
+</Accordion>
+
+<Accordion title="How do permission overrides work?">
+Permissions cascade from general to specific:
+1. **All Objects** sets the baseline for all objects
+2. **Object-Level Permissions** can override the global setting for specific objects
+3. **Field-Level Permissions** can override the object setting for specific fields
+
+More specific settings always take precedence.
+</Accordion>
+
+<Accordion title="What do the different permission levels mean?">
+For objects:
+- **See Records**: View records in lists and detail pages
+- **Edit Records**: Modify existing records
+- **Delete Records**: Soft-delete records (can be restored)
+- **Destroy Records**: Permanently delete records
+
+For fields:
+- **See Field**: View the field value
+- **Edit Field**: Modify the field value
+- **No Access**: Field is completely hidden
+</Accordion>
+
+<Accordion title="Can I restrict access to specific records (row-level permissions)?">
+Row-level permissions are available on the **Organization** plan. This allows you to restrict access to specific records based on criteria (e.g., only see your own opportunities).
+</Accordion>
+
+<Accordion title="How do I make a field read-only for certain users?">
+1. Go to **Settings → Members → Roles**
+2. Select the role
+3. Navigate to the object containing the field
+4. Set the field permission to **See Field** (without Edit Field)
+</Accordion>
+</AccordionGroup>
+
+## Settings & Actions
+
+<AccordionGroup>
+<Accordion title="What settings permissions are available?">
+You can control access to:
+- API key generation
+- Workspace preferences
+- Role assignment
+- Data model configuration
+- Security settings
+- Workflow management
+
+Use **Settings All Access** to grant full access, or enable specific permissions.
+</Accordion>
+
+<Accordion title="What action permissions are available?">
+You can control:
+- **Send Email**: Ability to send emails from Twenty
+- **Import CSV**: Ability to import data via CSV
+- **Export CSV**: Ability to export data to CSV
+
+Use **Application All Access** to grant all actions, or enable specific ones.
+</Accordion>
+</AccordionGroup>
+
+## SSO
+
+<AccordionGroup>
+<Accordion title="Is SSO available on all plans?">
+No, SSO is a Premium feature available on the **Organization** plan only.
+</Accordion>
+
+<Accordion title="Which identity providers are supported?">
+Twenty supports:
+- **SAML 2.0** (works with most enterprise identity providers)
+- **Google Workspace**
+- **Microsoft Entra ID** (formerly Azure AD)
+</Accordion>
+
+<Accordion title="What is Just-in-Time (JIT) provisioning?">
+With JIT provisioning, user accounts are automatically created in Twenty when someone logs in via SSO for the first time. They're assigned the default role automatically.
+</Accordion>
+
+<Accordion title="Can I require SSO for all users?">
+Yes, once SSO is configured, you can disable password login for SSO users to enforce authentication through your identity provider.
+</Accordion>
+</AccordionGroup>
+

packages/twenty-docs/user-guide/permissions-access/overview.mdx

@@ -0,0 +1,34 @@
+---
+title: Permissions & Access
+description: Manage roles, permissions, and access control in your workspace.
+---
+
+Twenty's permission system lets you control who can access and modify data in your workspace. Create roles, assign permissions, and configure SSO for secure access.
+
+## What's in this section
+
+<CardGroup cols={2}>
+  <Card title="Permissions" icon="lock" href="/user-guide/permissions-access/capabilities/permissions">
+    Create roles and configure object, field, and settings permissions.
+  </Card>
+  <Card title="SSO Configuration" icon="key" href="/user-guide/permissions-access/capabilities/sso-configuration">
+    Set up Single Sign-On with your identity provider.
+  </Card>
+  <Card title="FAQ" icon="circle-question" href="/user-guide/permissions-access/how-tos/permissions-faq">
+    Common questions about roles, permissions, and SSO.
+  </Card>
+</CardGroup>
+
+## Key features
+
+- **Role-based access**: Create custom roles with specific permissions
+- **Object permissions**: Control who can view, edit, or delete records
+- **Field permissions**: Restrict access to sensitive fields
+- **Settings permissions**: Control access to workspace configuration
+- **SSO integration**: Configure single sign-on for enterprise security (Organization plan)
+
+## Quick links
+
+- [Create a Role](/user-guide/permissions-access/capabilities/permissions#create-a-role)
+- [Configure SSO](/user-guide/permissions-access/capabilities/sso-configuration)
+- [Manage team members](/user-guide/settings/capabilities/member-management)