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>