Twenty Admin Guide

This guide is the operational and architectural reference for Twenty, the open-source CRM. It is written for administrators, DevOps engineers, and developers who deploy, configure, secure, operate, and extend a Twenty instance — whether self-hosted or integrated against Twenty Cloud.

It covers the system architecture, deployment with Docker Compose, the complete configuration surface, security model, day-to-day operations (backups, upgrades, key rotation, background jobs), the REST/GraphQL API, OAuth and webhooks, the Apps extensibility platform, and developer internals. End-user product walkthroughs live in the companion User Guide.

Important

Twenty's authoritative configuration reference is the decorated class packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts. This guide documents that surface (169 variables across 20 groups) and how the runtime resolves them. Where a value can change between releases, treat the in-app Settings → Admin Panel → Configuration Variables page as the live source of truth.

1. Executive Summary

Twenty is a developer-first CRM that treats the data model as a first-class, user-extensible asset. Unlike traditional CRMs with fixed objects and a config panel, Twenty lets administrators and developers define custom objects, fields, relations, views, workflows, and AI agents — each of which automatically gains its own API, permissions, and UI.

Note

Twenty originally used Prisma but moved to TypeORM specifically to get the lower-level control needed to support user-defined custom fields and objects at runtime. This decision shapes the whole data layer.

2. Architecture

2.1 Container topology

A standard deployment is four containers, defined in packages/twenty-docker/docker-compose.yml:

                         ┌─────────────────────────────────┐
        Browser  ───────▶│  server  (twentycrm/twenty)      │
        / API client     │  NestJS + GraphQL Yoga + React   │
                         │  port 3000, /healthz healthcheck │
                         │  runs DB migrations + cron reg.  │
                         └───────┬─────────────┬────────────┘
                                 │             │
                  ┌──────────────▼──┐   ┌──────▼───────────────┐
                  │  db  postgres:16│   │ redis (noeviction)   │
                  │  vol: db-data   │   │ cache + BullMQ queue │
                  └──────────────▲──┘   └──────▲───────────────┘
                                 │             │
                         ┌───────┴─────────────┴────────────┐
                         │  worker  (twentycrm/twenty)       │
                         │  cmd: yarn worker:prod            │
                         │  DISABLE_DB_MIGRATIONS=true       │
                         │  DISABLE_CRON_JOBS_REGISTRATION=true│
                         └───────────────────────────────────┘

Shared volume server-local-data is mounted into both server and worker at /app/packages/twenty-server/.local-storage for local file storage (used when STORAGE_TYPE=local).

Warning

Redis must run with maxmemory-policy noeviction. If Redis evicts keys under memory pressure, queued background jobs (email sync, calendar sync, workflows) can be silently lost.

2.2 The two database schemas

Provisioning creates two PostgreSQL schemas:

• core / default — workspace records (People, Companies, custom objects, etc.).
• metadata — the definition of each workspace's data model (objects, fields, relations).

If, after provisioning, you don't see both default and metadata schemas, you likely have more than one Postgres instance running. The metadata schema is what makes schema-per-tenant APIs possible: the API layer reads the metadata to generate REST/GraphQL endpoints that match each workspace's live model.

2.3 Request and data flow

1. The server serves the React app and exposes REST (/rest/*) and GraphQL (/graphql, /metadata) endpoints.
2. Mutations and queries run through TypeORM against PostgreSQL, scoped to the caller's workspace and role.
3. Long-running work (email/calendar import, workflow execution, AI agent steps, cleanup) is enqueued on BullMQ (backed by Redis) and executed by the worker.
4. Cron-scheduled jobs (registered by the server) drive recurring sync and maintenance.

2.4 Monorepo package map

Twenty is an Nx monorepo. The packages an administrator or integrator cares about most:

3. System Requirements

Note

For local development (contributing to Twenty itself), use the local setup with Node and Yarn rather than the production containers. This guide focuses on production/self-hosting; contributor setup is in the project's developers/contribute docs.

4. Deployment (Docker Compose)

Warning

The Docker images are for production hosting / self-hosting. For contributing to Twenty's source, use the local setup instead.

4.1 One-line install

Install the latest stable version:

bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)

To pin a version or branch:

VERSION=vx.y.z BRANCH=branch-name bash <(curl -sL https://raw.githubusercontent.com/twentyhq/twenty/main/packages/twenty-docker/scripts/install.sh)

4.2 Manual setup

Step 1 — Create the .env file.

curl -o .env https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/.env.example

The example .env:

TAG=latest

#PG_DATABASE_USER=postgres
#PG_DATABASE_PASSWORD=replace_me_with_a_strong_password_without_special_characters
#PG_DATABASE_HOST=db
#PG_DATABASE_PORT=5432
#REDIS_URL=redis://redis:6379

SERVER_URL=http://localhost:3000

# Use openssl rand -base64 32 for each secret
# ENCRYPTION_KEY=replace_me_with_a_random_string
# FALLBACK_ENCRYPTION_KEY= # set to the previous ENCRYPTION_KEY during a rotation
# APP_SECRET= # legacy: only required for instances that pre-date ENCRYPTION_KEY

STORAGE_TYPE=local

# STORAGE_S3_REGION=eu-west3
# STORAGE_S3_NAME=my-bucket
# STORAGE_S3_ENDPOINT=
# STORAGE_S3_ACCESS_KEY_ID=
# STORAGE_S3_SECRET_ACCESS_KEY=

Step 2 — Generate an encryption key.

openssl rand -base64 32

Put the result in ENCRYPTION_KEY.

Caution

Losing ENCRYPTION_KEY means losing access to every secret in the database — OAuth tokens, application variables, signing-key private keys, sensitive config values, and TOTP secrets. Store it in a secrets manager. Set a dedicated ENCRYPTION_KEY before first boot (and especially before upgrading to v2.5+, see §9.3).

Step 3 — Set the Postgres password. Update PG_DATABASE_PASSWORD with a strong password without special characters.

Step 4 — Get the Compose file.

curl -o docker-compose.yml https://raw.githubusercontent.com/twentyhq/twenty/refs/heads/main/packages/twenty-docker/docker-compose.yml

Step 5 — Launch.

docker compose up -d

Step 6 — Access. Visit http://localhost:3000, or on a server:

curl http://localhost:3000

The server runs all required upgrade migrations automatically on startup.

4.3 Exposing Twenty externally — SERVER_URL

By default Twenty runs on localhost:3000. To serve it on a domain, set SERVER_URL to exactly the URL users will use in their browser.

Direct access (no proxy)

SERVER_URL=http://your-domain-or-ip:3000

Reverse proxy + SSL (standard ports)

SERVER_URL=https://your-domain-or-ip

Reverse proxy + custom port

SERVER_URL=https://your-domain-or-ip:custom-port

Restart after changing it:

docker compose down
docker compose up -d

Important

SSL is required for some browser features (for example, the clipboard API used by copy buttons). Run Twenty behind a reverse proxy (Nginx, Traefik, Caddy) with SSL termination forwarding to internal port 3000, and ensure X-Forwarded-For and X-Forwarded-Proto headers are set. SERVER_URL must match the external URL exactly.

4.4 Persistence

The Compose configuration uses named volumes (db-data, server-local-data) to persist the database and local file storage. On stateless platforms, use external storage (S3) for uploads so files survive container restarts.

5. Configuration

5.1 Two configuration modes

Twenty resolves most configuration from either the database (admin panel) or environment variables, controlled by one flag:

Only users with canAccessFullAdminPanel: true can reach the admin configuration UI.

Important

Some settings are env-only regardless of mode because they're infrastructure or secrets: PG_DATABASE_URL, SERVER_URL, REDIS_URL, ENCRYPTION_KEY, FALLBACK_ENCRYPTION_KEY, APP_SECRET, and IS_MULTIWORKSPACE_ENABLED. These can only be set in .env and require a restart.

5.2 Configuration variable reference

The server defines 169 configuration variables grouped into 20 categories. The tables below list the key variables per group with their code defaults. The complete, always-current list with descriptions is in config-variables.ts and in the admin panel.

Server config (SERVER_CONFIG)

Storage (STORAGE_CONFIG)

Authentication — Google (GOOGLE_AUTH) and Microsoft (MICROSOFT_AUTH)

Related auth flags (in ADVANCED_SETTINGS): AUTH_PASSWORD_ENABLED (true), IS_EMAIL_VERIFICATION_REQUIRED (false), IS_IMAP_SMTP_CALDAV_ENABLED (true).

Email (EMAIL_SETTINGS)

Tokens & durations (TOKENS_DURATION)

Rate limiting (RATE_LIMITING)

Logic functions & code interpreter

Other groups

• BILLING_CONFIG — IS_BILLING_ENABLED (false), BILLING_STRIPE_API_KEY, BILLING_STRIPE_WEBHOOK_SECRET, trial durations (30/7 days), free workflow credits, BILLING_PLAN_REQUIRED_LINK.
• LLM — AI_PROVIDERS, AI_MODELS_DEFAULT_FAST / _SMART / _RECOMMENDED / _DISABLED. Configure AI providers and default models here.
• LOGGING — LOG_LEVELS (['log','error','warn']), LOGGER_DRIVER (CONSOLE), EXCEPTION_HANDLER_DRIVER, SENTRY_DSN / SENTRY_FRONT_DSN / SENTRY_ENVIRONMENT, TELEMETRY_ENABLED (true), METER_DRIVER.
• ANALYTICS_CONFIG — ANALYTICS_ENABLED (false), CLICKHOUSE_URL.
• SSL — SSL_KEY_PATH, SSL_CERT_PATH (for terminating TLS directly at the server).
• CLOUDFLARE_CONFIG — CLOUDFLARE_API_KEY, CLOUDFLARE_ZONE_ID, etc. (custom-domain automation).
• CAPTCHA_CONFIG — CAPTCHA provider/site/secret keys.
• SUPPORT_CHAT_CONFIG — SUPPORT_DRIVER (NONE), Front chat keys.
• AWS_SES_SETTINGS — AWS_SES_REGION, credentials, INBOUND_EMAIL_DOMAIN, SES_SNS_TOPIC_ARN_ALLOWLIST.
• ADVANCED_SETTINGS — workspace lifecycle (WORKSPACE_INACTIVE_DAYS_BEFORE_NOTIFICATION/_SOFT_DELETION/_DELETION = 7/14/21), OUTBOUND_HTTP_SAFE_MODE_ENABLED (true), WORKSPACE_SCHEMA_DDL_LOCKED (false), Postgres pool tuning (PG_POOL_MAX_CONNECTIONS=10, PG_POOL_IDLE_TIMEOUT_MS=600000), APP_REGISTRY_URL (https://registry.npmjs.org), maps/autocomplete keys.

5.3 Multi-workspace mode

By default Twenty runs single-workspace — ideal for one organization.

For multi-workspace, configure wildcard DNS so new subdomains route automatically:

*.your-domain.com -> your-server-ip

Restrict who can create workspaces with IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true.

Warning

IS_MULTIWORKSPACE_ENABLED is env-only and requires a restart; it cannot be toggled from the admin panel.

5.4 Google Workspace integration

1. In Google Cloud Console, create a project and enable the Gmail API, Google Calendar API, and People API.
2. Create an OAuth 2.0 Client ID and add redirect URIs:
   • https://{your-domain}/auth/google/redirect (SSO)
   • https://{your-domain}/auth/google-apis/get-access-token (integrations)
3. In Settings → Admin Panel → Configuration Variables → Google Auth, set:

MESSAGING_PROVIDER_GMAIL_ENABLED=true
CALENDAR_PROVIDER_GOOGLE_ENABLED=true
AUTH_GOOGLE_CLIENT_ID={client-id}
AUTH_GOOGLE_CLIENT_SECRET={client-secret}
AUTH_GOOGLE_CALLBACK_URL=https://{your-domain}/auth/google/redirect
AUTH_GOOGLE_APIS_CALLBACK_URL=https://{your-domain}/auth/google-apis/get-access-token

Required scopes (configured automatically): calendar.events, gmail.readonly, profile.emails.read.

5.5 Microsoft 365 integration

Important

Each user needs a Microsoft 365 license to sync calendar and mail. Personal Microsoft accounts are not supported (error AADSTS50020).

1. Create a project in Microsoft Azure and obtain credentials.
2. Grant Microsoft Graph permissions: Mail.ReadWrite, Mail.Send (only needed to send mail from workflow actions — Mail.Read suffices for receive-only), Calendars.Read, User.Read, openid, email, profile, offline_access.
3. Add redirect URIs: https://{your-domain}/auth/microsoft/redirect (SSO) and https://{your-domain}/auth/microsoft-apis/get-access-token.
4. Set the AUTH_MICROSOFT_* and provider-enabled variables (mirroring the Google block above).

5.6 Email (SMTP)

Set EMAIL_DRIVER=smtp and the SMTP variables. The default LOGGER driver only logs emails — switch to smtp to actually send.

Gmail

EMAIL_DRIVER=smtp
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=465
EMAIL_SMTP_USER=gmail_email_address
EMAIL_SMTP_PASSWORD='gmail_app_password'

Office 365

EMAIL_DRIVER=smtp
EMAIL_SMTP_HOST=smtp.office365.com
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=office365_email_address
EMAIL_SMTP_PASSWORD='office365_password'

smtp4dev (testing)

docker run --rm -it -p 8090:80 -p 2525:25 rnwood/smtp4dev

EMAIL_DRIVER=smtp
EMAIL_SMTP_HOST=localhost
EMAIL_SMTP_PORT=2525

Gmail and Office 365 require an app password when 2FA is enabled.

5.7 S3 storage

For production, store uploads in S3 (or S3-compatible MinIO / DigitalOcean Spaces) so files persist across restarts and scale across server replicas:

STORAGE_TYPE=S_3
STORAGE_S3_REGION=...
STORAGE_S3_NAME=...
STORAGE_S3_ENDPOINT=...
STORAGE_S3_ACCESS_KEY_ID=...
STORAGE_S3_SECRET_ACCESS_KEY=...

Tip

When using S3 with in-browser file downloads, configure the bucket's CORS to allow your Twenty frontend origin, or downloads that depend on CORS will fail.

5.8 Logic functions & code interpreter (security-sensitive)

Both run user-provided code, so they default to DISABLED in production.

Production AWS example:

LOGIC_FUNCTION_TYPE=LAMBDA
LOGIC_FUNCTION_LAMBDA_REGION=us-east-1
LOGIC_FUNCTION_LAMBDA_ROLE=arn:aws:iam::123456789:role/your-lambda-role
LOGIC_FUNCTION_LAMBDA_ACCESS_KEY_ID=your-access-key
LOGIC_FUNCTION_LAMBDA_SECRET_ACCESS_KEY=your-secret-key

Caution

Never run LOGIC_FUNCTION_TYPE=LOCAL or CODE_INTERPRETER_TYPE=LOCAL in production with untrusted code — the code executes directly on the host with no isolation. Use LAMBDA / E_2_B, or keep these disabled.

6. Security

6.1 Encryption at rest

Twenty encrypts secrets at rest inside a versioned envelope: every encrypted value is stored as enc:v2:<keyId>:<payload>, where <keyId> is an 8-hex prefix derived from ENCRYPTION_KEY. Six sites are encrypted: connected-account tokens, application variables, application-registration variables, signing-key private keys, sensitive config storage, and TOTP secrets.

If ENCRYPTION_KEY is unset, Twenty falls back to the legacy APP_SECRET for at-rest encryption (and session-cookie signing). New installs should always set a dedicated ENCRYPTION_KEY; APP_SECRET is deprecated and kept only for backward compatibility and to verify legacy HS256 tokens.

6.2 JWT signing keys

Access and refresh tokens are signed with asymmetric ES256 keypairs stored in core."signingKey", each tagged with a kid. Exactly one key is isCurrent; public keys are retained indefinitely so previously issued tokens still verify. See §9.4 for rotation and revocation.

6.3 Authentication options

6.4 Network & request safety

• OUTBOUND_HTTP_SAFE_MODE_ENABLED=true (default) guards outbound HTTP from workflow/logic actions against hitting internal addresses (SSRF protection).
• Rate limiting (§5.2) caps API and workflow execution.
• TRUST_PROXY controls which proxy hops are trusted for client IP resolution — set it correctly behind your reverse proxy.

6.5 Permissions model

Role-based access control applies at object, field, and record level. API keys are scoped to a role (Settings → Members → Roles → Assignment), so a key can be limited to exactly what it needs. AI agents act under a role and cannot exceed it.

Important

Treat workspace data ownership as a feature: self-hosting keeps all CRM data on your infrastructure for compliance and data-residency requirements. Combine that with scoped roles, sandboxed logic functions, and rotated keys for a defensible posture.

7. Operations

7.1 Lifecycle commands

docker compose up -d        # start
docker compose down         # stop
docker compose logs         # view logs
docker compose logs -f server   # follow the server
docker compose ps           # status

7.2 Server admin commands

The server ships a command CLI (run inside the server or worker container via yarn command:prod <name>, or npx nx run twenty-server:command:prod <name>). Major commands:

7.3 Background (cron) jobs

The server registers recurring jobs; the worker executes them. After configuring Gmail / Google Calendar / Microsoft 365, register the sync jobs in the worker:

yarn command:prod cron:messaging:messages-import
yarn command:prod cron:messaging:message-list-fetch
yarn command:prod cron:calendar:calendar-event-list-fetch
yarn command:prod cron:calendar:calendar-events-import
yarn command:prod cron:messaging:ongoing-stale
yarn command:prod cron:calendar:ongoing-stale
yarn command:prod cron:workflow:automated-cron-trigger

Other registered cron jobs include: cron:register:all, cron:trash-cleanup, cron:event-log-cleanup, cron:stale-registration-cleanup, cron:clean-onboarding-workspaces, cron:clean-suspended-workspaces, cron:rotate-signing-keys, cron:enterprise-key-validation, cron:marketplace-catalog-sync, cron:app-version-check, cron:workflow:clean-workflow-runs, cron:workflow:handle-staled-runs, cron:workflow:enqueue-awaiting-workflow-run, cron:public-domain:check-public-domains-valid-records, and the cron:messaging:* / cron:calendar:* relaunch-failed-channel jobs.

Tip

A quick way to confirm the worker is alive: create a webhook (Settings → enable Advanced → Webhooks) pointing at a request-bin URL filtered to Companies + Created, then create a company. If the POST arrives, the worker is running.

7.4 Backup and restore

Single-database dump:

docker exec twenty-postgres pg_dump -U postgres twenty > backup_$(date +%Y%m%d).sql

Automated daily backup (crontab):

0 2 * * * docker exec twenty-postgres pg_dump -U postgres twenty > /backups/twenty_$(date +\%Y\%m\%d).sql

Full-cluster dump (recommended before upgrades):

docker exec -it {db_container} pg_dumpall -U {postgres_user} > databases_backup.sql

Restore:

docker compose stop server worker
cat databases_backup.sql | docker exec -i {db_container} psql -U {postgres_user}
docker compose up -d

Tip

Test restores regularly, store backups off-site (S3/GCS), encrypt them, and keep daily/weekly/monthly retention tiers.

7.5 Health & observability

• Health endpoint: GET /healthz (used by the Compose healthcheck).
• Errors: configure SENTRY_DSN / SENTRY_FRONT_DSN / SENTRY_ENVIRONMENT.
• Metrics: METER_DRIVER and OTLP_COLLECTOR_METRICS_ENDPOINT_URL (OpenTelemetry collector config ships under twenty-docker/otel-collector and twenty-docker/grafana).
• HEALTH_METRICS_TIME_WINDOW_IN_MINUTES (5) controls the health metrics window.

8. Operations Checklist

• [ ] .env created from .env.example
• [ ] ENCRYPTION_KEY generated with openssl rand -base64 32 and stored in a secrets manager
• [ ] PG_DATABASE_PASSWORD set to a strong value (no special characters)
• [ ] SERVER_URL matches the external browser URL
• [ ] Reverse proxy with SSL termination configured; X-Forwarded-* headers passed
• [ ] STORAGE_TYPE=S_3 configured for production uploads
• [ ] EMAIL_DRIVER=smtp configured (or LOGGER intentionally)
• [ ] OAuth (Google/Microsoft) configured if email/calendar sync is needed
• [ ] Sync cron jobs registered in the worker
• [ ] Logic functions / code interpreter set to DISABLED or a sandboxed driver
• [ ] Automated database backups scheduled and a restore tested
• [ ] Redis confirmed running with noeviction
• [ ] Admin user has canAccessFullAdminPanel

9. Upgrades & Key Rotation

9.1 Standard upgrade

docker compose down
# edit TAG in .env to the new version
docker compose up -d

The server runs required migrations automatically on startup. No manual migration command is needed.

9.2 Cross-version upgrades

From v1.22+, Twenty supports cross-version upgrades — jump directly from any supported version to the latest (for example, v1.22 → v2.0). Before v1.22, upgrade incrementally through each major tag (v1.6 → v1.7 → …) until you reach v1.22, then jump.

9.3 Upgrading to v2.5+ (encryption envelope)

From v2.5, at-rest secrets move into the enc:v2: envelope. First boot on v2.5 runs idempotent backfill commands that rewrite existing rows. They resume if interrupted but can take a while on large databases — monitor with upgrade:status.

Important

Set a dedicated ENCRYPTION_KEY before the v2.5 upgrade so the backfill writes under it from the start. Switching keys afterward requires a full rotation (§9.4).

9.4 Checking upgrade status

docker exec -it {server_container} yarn command:prod upgrade:status

APP_VERSION: v1.23.0

Instance
    Inferred version: 1.23.0
    Status:           Up to date

Summary
    Instance: Up to date
    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)

If an upgrade fails on some workspaces, the server won't advance past the failing step; restarting retries from where it left off. Use --failed-only to find and read the errors.

9.5 Rotating ENCRYPTION_KEY

Online and resumable (the secret-encryption:rotate command ships in v2.6+):

1. Generate a new key: openssl rand -base64 32.
2. Configure both keys and restart — new writes use the new key, old rows decrypt via the fallback:

   ENCRYPTION_KEY=NEW_VALUE
   FALLBACK_ENCRYPTION_KEY=OLD_VALUE
   

3. Re-encrypt existing rows:

   docker exec -it {server_container} yarn command:prod secret-encryption:rotate
   

   Flag	Description
   -s, --site <site>	Limit to one site
   -b, --batch-size <n>	Rows per batch (default 200, max 5000)
   -d, --dry-run	Decrypt + re-encrypt in memory, skip the UPDATE

4. When a --dry-run shows zero remaining rows, remove FALLBACK_ENCRYPTION_KEY and restart.

The command is idempotent (a SQL filter skips rows already on the new keyId) — interrupt and re-run freely. It exits non-zero if any row fails.

9.6 Rotating / revoking JWT signing keys

• Auto-rotation (v2.6+): set SIGNING_KEY_ROTATION_DAYS to issue a new current key once the existing one exceeds that age (via the cron:rotate-signing-keys job). Previous keys aren't revoked, so existing tokens keep verifying. Leave unset to disable.
• Emergency revoke: Settings → Admin Panel → Signing keys → Revoke on a non-current row. This wipes the encrypted private material, sets revokedAt, and rejects every token signed under that kid.

10. The API

10.1 Schema-per-tenant

There is no static API reference. Each workspace has its own schema; when you add a custom object (say Invoice), it immediately gets REST and GraphQL endpoints identical to built-in objects — using your object and field names directly (no opaque IDs). Your workspace-specific docs and an interactive playground are at Settings → API & Webhooks after creating an API key.

10.2 Two APIs

GraphQL adds batch upserts and single-query relation traversal. Same underlying data either way.

10.3 Base URLs and auth

Authorization: Bearer YOUR_API_KEY

Create a key in Settings → API & Webhooks → + Create key (shown once — copy immediately). Scope it to a role to limit access.

10.4 Batching and rate limits

GraphQL also supports batch upsert using plural names (e.g. CreateCompanies).

11. OAuth 2.0

Twenty implements OAuth 2.0 with authorization code + PKCE for user-facing apps and client credentials for server-to-server access. Clients register dynamically per RFC 7591 — no dashboard setup.

11.1 Endpoints

11.2 Register a client

POST /oauth/register
Content-Type: application/json

{
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "client_secret_post"
}

Warning

Store the returned client_secret securely — it cannot be retrieved later.

11.3 Scopes

Request as a space-separated string: scope=api profile.

11.4 Authorization code flow

1. Redirect the user to /oauth/authorize with client_id, response_type=code, redirect_uri, scope, a random state, and a PKCE code_challenge (code_challenge_method=S256).
2. Handle the callback at your redirect_uri?code=...&state=...; verify state.
3. Exchange the code at /oauth/token with grant_type=authorization_code, the code, redirect_uri, client credentials, and code_verifier. You receive access_token, refresh_token, and expires_in (3600 s).
4. Call the API with Authorization: Bearer ACCESS_TOKEN.
5. Refresh with grant_type=refresh_token.

11.5 Client credentials flow

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...&scope=api

The token has workspace-level access, not tied to a user.

12. Webhooks

Twenty POSTs to your URL whenever a record is created, updated, or deleted — for all object types, including custom objects.

12.1 Create

Settings → APIs & Webhooks → Webhooks → + Create webhook → enter a publicly reachable URL → Save. It activates immediately.

12.2 Events & payload

{
  "event": "person.created",
  "data": { "id": "abc12345", "firstName": "Alice", "lastName": "Doe", "email": "[email removed]", "createdAt": "2025-02-10T15:30:45Z", "createdBy": "user_123" },
  "timestamp": "2025-02-10T15:30:50Z"
}

Respond with a 2xx status to acknowledge; non-2xx responses are logged as delivery failures.

12.3 Signature validation

Each request is signed:

Validate by computing HMAC_SHA256(secret, "{timestamp}:{payload}") and comparing (constant-time) to the signature header:

const crypto = require("crypto");
const timestamp = req.headers["x-twenty-webhook-timestamp"];
const payload = JSON.stringify(req.body);
const stringToSign = `${timestamp}:${payload}`;
const expected = crypto.createHmac("sha256", secret).update(stringToSign).digest("hex");
const isValid = crypto.timingSafeEqual(
  Buffer.from(expected, "hex"),
  Buffer.from(req.headers["x-twenty-webhook-signature"], "hex")
);

12.4 Webhooks vs workflows

13. Extending Twenty — Apps

Apps are TypeScript packages (built with twenty-sdk) that extend Twenty with code: objects/fields, server-side logic, sandboxed UI, and AI capabilities.

13.1 What an app defines

Entities are detected by AST analysis at build time — put export default defineObject(...) in any .ts file and the SDK picks it up. Logic functions run in isolated Node processes via a typed API client scoped to the app's role; permissions are enforced at the API level.

13.2 The app-development CLI (yarn twenty)

Distinct from the server command CLI. Key commands:

Remote credentials are stored in ~/.twenty/config.json.

13.3 Distribution

• Tarball (private): yarn twenty app:publish --private uploads to a server. Sharing a private app across workspaces is an Enterprise feature. Version in package.json must be strictly higher than the deployed version (VERSION_ALREADY_EXISTS otherwise).
• npm marketplace: add the twenty-app keyword to package.json and run yarn twenty app:publish. The server syncs the npm catalog hourly (or trigger dev:catalog-sync).
• Server compatibility: declare engines.twenty (a semver range, e.g. >=2.3.0) in package.json; the server rejects installs that don't satisfy it (SERVER_VERSION_INCOMPATIBLE). MAX_TARBALL_UPLOAD_SIZE_BYTES caps tarball size (100 MB default).

Scaffolded apps ship GitHub Actions for CI (ephemeral test instance) and CD (deploy on push to main, needs TWENTY_DEPLOY_URL and a TWENTY_DEPLOY_API_KEY secret).

14. Developer Internals

14.1 Backend commands (contributor)

Run from packages/twenty-server (or npx nx run twenty-server:<command>):

npx nx run twenty-server:database:reset            # set up DB with dev seeds
npx nx run twenty-server:start                     # start the server
npx nx run twenty-server:worker                    # start the worker
npx nx run twenty-server:lint                      # lint (--fix to autofix)
npx nx run twenty-server:test:unit                 # unit tests
npx nx run twenty-server:test:integration          # integration tests
npx nx run twenty-server:database:migrate:generate # generate a TypeORM migration

14.2 Tech stack

• Backend: NestJS, TypeORM, GraphQL Yoga (Twenty moved off Prisma to TypeORM for custom-object/field support).
• Database: PostgreSQL.
• Queue: BullMQ on Redis.
• Testing: Jest. Tooling: Yarn, Oxlint (Oxc). Errors: Sentry.
• Frontend: React, Jotai, Linaria, Lingui.

14.3 Repository layout (high level)

packages/
  twenty-server/    NestJS backend (API, auth, metadata, workflows, jobs, config-variables.ts)
  twenty-front/     React app
  twenty-docker/    Compose, Helm, k8s, install scripts, postgres image, otel/grafana
  twenty-cli/ twenty-sdk/ create-twenty-app/   App-dev tooling
  twenty-ui/ twenty-shared/ twenty-utils/      Shared libraries
  twenty-emails/    Email templates
  twenty-zapier/    Zapier integration
  twenty-docs/ twenty-website/                  Docs + marketing

15. Troubleshooting

password authentication failed for user "postgres" on first install

The first-boot password is baked into the DB volume. For fresh installs only (this deletes data):

# update PG_DATABASE_PASSWORD in .env first
docker compose down --volumes
docker compose up -d

Caution

Never run down --volumes on an instance with production data — it permanently deletes the database.

Admin panel not accessible

Grant yourself admin in the DB:

UPDATE core."user" SET "canAccessFullAdminPanel" = TRUE WHERE email = '[email removed]';

Missing metadata schema after provisioning

Ensure only one Postgres instance is running on the host — a second instance causes provisioning to target the wrong database.

Workflow run fails: "Logic function execution is disabled…"

Logic functions default to disabled in production. Set LOGIC_FUNCTION_TYPE=LOCAL (trusted only) or LAMBDA via env or the admin panel (§5.8).

No emails sent / worker not running

Confirm the worker container is up. In dev, npx nx worker twenty-server. Verify with the webhook test in §7.3. Also check EMAIL_DRIVER is smtp (the default LOGGER only logs).

Connection issues behind a reverse proxy

Verify SERVER_URL matches the external URL (with https if SSL), that the proxy forwards to internal port 3000, and that X-Forwarded-For / X-Forwarded-Proto are set. Restart proxy and containers after changes.

Image upload fails: permission denied

Fix ownership of the data folder on the host (switch it off root to the user/group the container runs as), or move to S3 storage.

Can't log in after a 1-click setup

docker exec -it twenty-server-1 yarn
docker exec -it twenty-server-1 npx nx database:reset --configuration=no-seed
docker compose down && docker compose up -d

Caution

database:reset erases and recreates the database.

Out-of-memory on dev start

Run only the services you need (e.g. npx nx worker twenty-server) and raise the Node heap: export NODE_OPTIONS="--max-old-space-size=8192".

16. Quick Reference