Twenty connector

The Twenty connector exposes a fixed workspace-aware REST surface as governed AIP capabilities. Use it to manage standard or custom records, inspect or change selected workspace metadata, read generated OpenAPI documents, and ingest signed Twenty webhook events.

The connector is not an arbitrary HTTP or GraphQL proxy. Provider paths, operation names, query keys, credential placement, request limits, approval, idempotency, retry, response handling, and webhook verification are fixed in source.

Decide whether it fits

Choose a separate, narrowly reviewed connector when an excluded provider surface is required. Do not add a caller-selected path or credential to an Action.

Fix the reviewed identity

The upstream commit is the mapping reference recorded by connector source. A deployed Twenty image, edition, migration state, and workspace schema require their own identity and evidence.

Understand the deployment boundary

One standalone aip-host-twenty process owns:

• one AIP tenant, connector instance, and concrete replica;
• one configured Twenty workspace UUID;
• one fixed Twenty origin;
• one owner-controlled API-token file;
• one optional owner-controlled webhook-secret file;
• one optional operation allowlist;
• durable AIP runtime, replay, event, and outbox state;
• native AIP signing, lifecycle, routing, and credential-revision policy.

The host receives signed AIP Actions and sends synchronous REST requests with a Bearer header. It disables redirects and adds the AIP Action ID to provider requests.

Keep one host instance bound to one tenant and intended Twenty workspace. The workspace UUID participates in deterministic create IDs, manifest identity, webhook validation, and external-account routing.

Read the capability groups

Capability IDs use cap:twenty:<operation>, such as cap:twenty:record.list or cap:twenty:metadata.update.

An optional operations file can reduce the 22-operation catalogue. An empty allowlist is invalid. Deployment policy cannot introduce an unknown operation.

Use the fixed record surface

Record Actions name an object matching ^[A-Za-z][A-Za-z0-9_]{0,127}$. This permits Twenty standard and custom object names without allowing path separators or arbitrary provider routes.

Single-record operations require an RFC 4122 UUID version 1 through 5. Bulk update, soft-delete, destroy, and restore require a non-empty provider filter.

Create and create-many operations force Twenty upsert=true. When a body lacks an ID, the connector derives a deterministic UUID version 5 from workspace, idempotency key, and item index.

An explicit valid record UUID is preserved. Batch create accepts one through 200 record objects.

Restore-one uses Twenty’s filtered collection restore route because the pinned provider revision rejects the documented single-record restore path. The connector injects an exact ID filter after validating the requested UUID.

Use only allowlisted metadata

The metadata surface includes:

• objects and fields;
• views, viewFields, viewFilters, viewGroups, viewSorts, and viewFilterGroups;
• pageLayouts, pageLayoutTabs, and pageLayoutWidgets;
• webhooks.

Each list resource accepts only its provider-specific query keys. Page-layout tabs require pageLayoutId; widgets require pageLayoutTabId.

Webhook metadata has an additional secret boundary. Action input cannot supply secret. Create injects the configured host secret, and update injects it only when rotateConfiguredSecret is exactly true.

The connector recursively removes every secret key from webhook metadata responses.

Apply governance by operation

The two permanent-destroy operations are also critical. Every mutation requires tenant-policy approval with reason, input snapshot, and policy decision. Approval expires after 15 minutes.

Mutation idempotency is scoped to the external account, uses input-hash revalidation, and declares a seven-day contract TTL. The connector forwards the key but does not provide a local provider-effect reconciliation API.

All operations are synchronous. The connector publishes no async, streaming, cancellation, transaction, reconciliation, or compensation support.

Interpret retry safety narrowly

The eleven retry-safe operations are the eight reads plus create, create-many, and update-one. The create paths use deterministic IDs and force provider upsert.

Update-many, deletes, restore, merge, and metadata mutations remain retry-unsafe. A 429 or 5xx response marks every mutation outcome uncertain, including a retry-safe mutation.

Transport failure is retryable only when the operation contract permits it and the connector can classify the failure safely. Reconcile the original Action and provider state before retrying any uncertain mutation.

Protect data and credentials

Every capability declares confidential data, possible personal data, and required redaction. Record bodies, query filters, metadata, OpenAPI documents, webhook payloads, and provider errors can expose workspace structure or customer data.

The API token remains in an owner-controlled file and is used only as a Bearer header. It must be UTF-8, at most 16 KiB, and contain no whitespace or DEL.

The webhook HMAC secret is separate. It is injected into webhook metadata only inside the host and never accepted from protocol input.

Provider error output retains only bounded allowlisted fields. Provider request identity accepts a bounded x-request-id or traceparent value without control characters.

Understand webhook ingress

Webhook ingress is absent unless a secret file is configured. When enabled, the host also requires a central connector-event endpoint.

The fixed route /webhooks/twenty requires timestamp, signature, and nonce headers. Verification uses HMAC-SHA-256 over exact bytes:

<decimal timestamp>:<raw request body>

The timestamp must be within five minutes. The signature is 64 hexadecimal characters, and the nonce is 32 hexadecimal characters.

The host validates workspace ID, webhook UUID, RFC 3339 event time, event-name syntax, and JSON object shape. A durable compare-and-swap store admits each nonce once, with a bounded 100,000-nonce window.

An accepted delivery becomes a deterministic AIP event, enters the durable event log, then enters the central outbox. HTTP success reports whether central delivery was newly queued or already present.

Respect the transport bounds

Response reading is streaming but the AIP operation is not. The connector buffers one bounded JSON response and rejects invalid JSON.

Know the maturity boundary

The reviewed source contains contract tests and a standalone host. Its generic image verifier builds the Twenty host, but the pinned five-product Compose qualification topology does not include a Twenty service.

Local retained evidence may describe another exact Twenty run. It does not qualify an unspecified rebuilt artifact or a different workspace automatically.

Before adoption, qualify the exact host digest, Twenty deployment, workspace, schema, credentials, operation allowlist, webhook path, and failure topology.

Know what is excluded

The reviewed connector does not expose:

• arbitrary REST paths or HTTP methods;
• arbitrary GraphQL documents;
• API-token creation or credential material in AIP;
• file upload or attachment workflows;
• application, workflow, calendar, email, or telephony surfaces outside the fixed record and metadata catalogues;
• provider transactions or multi-operation atomicity;
• cancellation or streaming;
• provider rollback, AIP compensation, or automatic reconciliation;
• schema-specific validation of dynamic record bodies;
• compatibility with an unrecorded Twenty revision.

Choose the next path

Start with the connector catalogue for scope, then read the AIP execution model before sending Actions. Use the fleet guide for the standalone host, the error reference before implementing retries, and the upstream-baseline page when reviewing provider identity.

Related documentation

• Connector catalog
• How AIP works
• Deploy the connector fleet
• Errors and retry decisions
• Connector upstream baselines