Authentication & Security

Relevant source files

The following files were used as context for generating this wiki page:

• packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md
• packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md
• packages/twenty-codex-plugin/AGENTS.md
• packages/twenty-codex-plugin/references/develop-app/data-model.md
• packages/twenty-shared/src/constants/DocumentationPaths.ts
• packages/twenty-codex-plugin/skills/develop-app/SKILL.md

Authentication and Security in Twenty covers the multi-layered approach to protecting workspace data, managing user access, and securing app extensions. This system encompasses product-level features such as Single Sign-On (SSO) and row-level security, as well as developer-focused security protocols for OAuth connections and API key management.

The architecture is designed to enforce the principle of least privilege, ensuring that users and automated processes only access the specific resources required for their operations. This is achieved through a combination of object-level, field-level, and row-level permissions gated by workspace plans.

Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md, packages/twenty-codex-plugin/references/develop-app/data-model.md

Roles and Permissions

Twenty utilizes a comprehensive permissions model that defines what users can read, create, update, or delete within a workspace. These permissions are organized into roles that should match operational responsibility rather than implementation convenience.

Permission Layers

Security is enforced at three distinct layers:

1. Object-Level: Controls access to entire data entities (e.g., Opportunities, Persons).
2. Field-Level: Restricts access to specific attributes within an object (e.g., salary field on a Person object).
3. Row-Level Security (RLS): Provides granular control over specific records based on data attributes or ownership. RLS is a premium product feature typically available on the Organization plan.

Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:214-231, packages/twenty-codex-plugin/references/develop-app/data-model.md:72-82

Role Management

Roles are defined to grant the smallest useful scope. When implementing roles in apps, developers must account for side effects introduced by logic functions before granting write access.

The diagram above illustrates how a user's access to workspace data is filtered through assigned roles and multiple permission layers.
Sources: packages/twenty-codex-plugin/references/develop-app/data-model.md:72-82

Connection Security and OAuth

Twenty supports integrations with external systems (e.g., Gmail, Slack, WhatsApp) through Connection Providers and OAuth.

Security Guidelines for Connections

• Credential Isolation: Bearer tokens, API keys, and OAuth secrets must never be committed to source control. They are managed as user-local or environment-specific variables.
• Redirect URIs: OAuth connections for apps use a standardized redirect URI format: <SERVER_URL>/apps/oauth/callback.
• Public Assets: Files stored in the public/ folder of an app are served without authentication. Developers must never store secrets, private customer records, or real tokens in these assets.

Sources: packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md:27-33, 91-95, packages/twenty-codex-plugin/AGENTS.md:74-78

OAuth Flow Logic

This sequence shows the secure exchange of authorization codes and tokens between Twenty and external providers.
Sources: packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md:91-95

Infrastructure and Compliance

Twenty provides flexible deployment options that impact the security and compliance posture of the workspace.

Deployment and Hosting

Workspaces can be hosted on the Twenty Cloud or self-hosted via Docker. Security requirements often dictate the choice of hosting:

• Cloud Hosting: Includes managed regions and provides options for EU data residency.
• Self-Hosting: Requires manual management of infrastructure security, PostgreSQL, and Redis instances.

Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:218-223, packages/twenty-shared/src/constants/DocumentationPaths.ts:109-116

Compliance Standards

The platform accounts for global data protection regulations, specifically GDPR, by allowing configuration for data residency and restricted data access.

Feature	Description	Requirement
GDPR Compliance	Protection of personal data for EU citizens	Deployment in EU regions
Data Residency	Ensuring data stays within specific geographic boundaries	Specific Cloud Plan / Self-host
SSO	Single Sign-On for centralized identity management	Enterprise/Organization Plan

Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:58-61, 218-223, packages/twenty-shared/src/constants/DocumentationPaths.ts:192-195

Developer Security Practices

When developing apps or extensions for Twenty, specific security protocols are enforced to prevent data leaks and unauthorized access.

Secure App Development

• One-Shot Sync: Developers are instructed to use yarn twenty dev --once for synchronization. Watch mode is discouraged in agent environments to prevent handle leaks and ambiguous failures.
• Entity Generation: Using yarn twenty dev:add is the preferred method for creating objects and fields as it ensures correct UUID generation and SDK boilerplate, reducing manual errors that could lead to security gaps.
• Data Masking in Screenshots: When preparing app listings for the marketplace, developers must use synthetic or seeded data only. Real customer data must never appear in visual assets.

Sources: packages/twenty-codex-plugin/AGENTS.md:43-47, packages/twenty-codex-plugin/skills/develop-app/SKILL.md:98-106, packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md:113-118

Logic Function Safety

Logic functions and post-install hooks must be kept narrow to minimize the attack surface. Complex logic should be extracted into pure helpers under src/utils/ to ensure they are testable and isolated from the main trigger execution.
Sources: packages/twenty-codex-plugin/skills/develop-app/SKILL.md:58-70

Authentication and security in Twenty are foundational components that scale from individual user permissions to complex organizational compliance requirements, ensuring data integrity across both core CRM functions and modular app extensions.