{
  "schemaVersion": "1.0",
  "title": "Twenty connector",
  "description": "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 ",
  "canonical": "https://getaip.org/docs/connectors/twenty",
  "route": "/docs/connectors/twenty",
  "source": "docs/connectors/twenty/README.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/twenty.md",
    "txt": "/docs/download/connectors/twenty.txt",
    "json": "/docs/download/connectors/twenty.json",
    "pdf": "/docs/download/connectors/twenty.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Twenty connector\ndescription: >-\n  Decide whether the Twenty connector fits a workspace integration and\n  understand its record, metadata, OpenAPI, and webhook boundaries\nkind: connector-overview\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: twenty\n---\n\n# Twenty connector\n\nThe Twenty connector exposes a fixed workspace-aware REST surface as governed\nAIP capabilities. Use it to manage standard or custom records, inspect or\nchange selected workspace metadata, read generated OpenAPI documents, and\ningest signed Twenty webhook events.\n\nThe connector is not an arbitrary HTTP or GraphQL proxy. Provider paths,\noperation names, query keys, credential placement, request limits, approval,\nidempotency, retry, response handling, and webhook verification are fixed in\nsource.\n\n## Decide whether it fits\n\n| Requirement | Fit |\n|---|---|\n| Query standard and custom object records | Yes |\n| Create, batch upsert, update, soft-delete, destroy, restore, or merge records | Yes, through fixed operations |\n| Find duplicates or run provider-native group-by | Yes |\n| Manage object, field, view, layout, and webhook metadata | Yes, for twelve allowlisted resources |\n| Read workspace-specific core and metadata OpenAPI documents | Yes |\n| Receive signed Twenty webhook events through AIP | Yes, when ingress security and event delivery are configured |\n| Call arbitrary REST paths | No |\n| Execute arbitrary GraphQL | No |\n| Create or expose Twenty API keys | No |\n| Stream, cancel, transact, compensate, or automatically reconcile provider work | No |\n| Prove compatibility with any Twenty revision or deployment | No |\n\nChoose a separate, narrowly reviewed connector when an excluded provider\nsurface is required. Do not add a caller-selected path or credential to an\nAction.\n\n## Fix the reviewed identity\n\n| Property | Reviewed value |\n|---|---|\n| AIP source | `97be86e9efedf07ecf1783b03800f683f107fb04` |\n| Connector crate | `aip-connector-twenty` `1.0.0` workspace line |\n| Standalone host | `aip-host-twenty` `1.0.0` workspace line |\n| Connector profile | `aip.connector.twenty.v1` |\n| AIP protocol | `1.0` |\n| Upstream mapping revision | `96a24563674313a3071d359bfccaf33d5e130ab8` |\n| Operation catalogue | 22 fixed operations |\n| Metadata catalogue | 12 fixed resources |\n\nThe upstream commit is the mapping reference recorded by connector source. A\ndeployed Twenty image, edition, migration state, and workspace schema require\ntheir own identity and evidence.\n\n## Understand the deployment boundary\n\nOne standalone `aip-host-twenty` process owns:\n\n- one AIP tenant, connector instance, and concrete replica;\n- one configured Twenty workspace UUID;\n- one fixed Twenty origin;\n- one owner-controlled API-token file;\n- one optional owner-controlled webhook-secret file;\n- one optional operation allowlist;\n- durable AIP runtime, replay, event, and outbox state;\n- native AIP signing, lifecycle, routing, and credential-revision policy.\n\nThe host receives signed AIP Actions and sends synchronous REST requests with a\nBearer header. It disables redirects and adds the AIP Action ID to provider\nrequests.\n\nKeep one host instance bound to one tenant and intended Twenty workspace. The\nworkspace UUID participates in deterministic create IDs, manifest identity,\nwebhook validation, and external-account routing.\n\n## Read the capability groups\n\n| Group | Operations | Purpose |\n|---|---:|---|\n| Record query | 4 | List, get, find duplicates, and group records |\n| Record create and update | 4 | Create, create many, update, and update many |\n| Record lifecycle | 7 | Soft-delete, destroy, restore, and merge |\n| Metadata | 5 | List, get, create, update, and delete allowlisted resources |\n| OpenAPI | 2 | Read workspace core and metadata documents |\n\nCapability IDs use `cap:twenty:<operation>`, such as\n`cap:twenty:record.list` or `cap:twenty:metadata.update`.\n\nAn optional operations file can reduce the 22-operation catalogue. An empty\nallowlist is invalid. Deployment policy cannot introduce an unknown operation.\n\n## Use the fixed record surface\n\nRecord Actions name an object matching\n`^[A-Za-z][A-Za-z0-9_]{0,127}$`. This permits Twenty standard and custom object\nnames without allowing path separators or arbitrary provider routes.\n\nSingle-record operations require an RFC 4122 UUID version 1 through 5. Bulk\nupdate, soft-delete, destroy, and restore require a non-empty provider filter.\n\nCreate and create-many operations force Twenty `upsert=true`. When a body lacks\nan ID, the connector derives a deterministic UUID version 5 from workspace,\nidempotency key, and item index.\n\nAn explicit valid record UUID is preserved. Batch create accepts one through\n200 record objects.\n\nRestore-one uses Twenty's filtered collection restore route because the pinned\nprovider revision rejects the documented single-record restore path. The\nconnector injects an exact ID filter after validating the requested UUID.\n\n## Use only allowlisted metadata\n\nThe metadata surface includes:\n\n- `objects` and `fields`;\n- `views`, `viewFields`, `viewFilters`, `viewGroups`, `viewSorts`, and\n  `viewFilterGroups`;\n- `pageLayouts`, `pageLayoutTabs`, and `pageLayoutWidgets`;\n- `webhooks`.\n\nEach list resource accepts only its provider-specific query keys. Page-layout\ntabs require `pageLayoutId`; widgets require `pageLayoutTabId`.\n\nWebhook metadata has an additional secret boundary. Action input cannot supply\n`secret`. Create injects the configured host secret, and update injects it only\nwhen `rotateConfiguredSecret` is exactly `true`.\n\nThe connector recursively removes every `secret` key from webhook metadata\nresponses.\n\n## Apply governance by operation\n\n| Class | Count | Approval | Idempotency | Retry contract | Risk |\n|---|---:|---|---|---|---|\n| Reads | 8 | No connector-required approval | Optional | Safe | Low |\n| Create one or many, update one | 3 | Required | Required | Safe with key | High |\n| Other record mutations | 8 | Required | Required | Unsafe | High, except permanent destroy |\n| Metadata mutations | 3 | Required | Required | Unsafe | Critical |\n\nThe two permanent-destroy operations are also critical. Every mutation requires\ntenant-policy approval with reason, input snapshot, and policy decision.\nApproval expires after 15 minutes.\n\nMutation idempotency is scoped to the external account, uses input-hash\nrevalidation, and declares a seven-day contract TTL. The connector forwards the\nkey but does not provide a local provider-effect reconciliation API.\n\nAll operations are synchronous. The connector publishes no async, streaming,\ncancellation, transaction, reconciliation, or compensation support.\n\n## Interpret retry safety narrowly\n\nThe eleven retry-safe operations are the eight reads plus create, create-many,\nand update-one. The create paths use deterministic IDs and force provider\nupsert.\n\nUpdate-many, deletes, restore, merge, and metadata mutations remain retry-unsafe.\nA `429` or `5xx` response marks every mutation outcome uncertain, including a\nretry-safe mutation.\n\nTransport failure is retryable only when the operation contract permits it and\nthe connector can classify the failure safely. Reconcile the original Action\nand provider state before retrying any uncertain mutation.\n\n## Protect data and credentials\n\nEvery capability declares confidential data, possible personal data, and\nrequired redaction. Record bodies, query filters, metadata, OpenAPI documents,\nwebhook payloads, and provider errors can expose workspace structure or customer\ndata.\n\nThe API token remains in an owner-controlled file and is used only as a Bearer\nheader. It must be UTF-8, at most 16 KiB, and contain no whitespace or DEL.\n\nThe webhook HMAC secret is separate. It is injected into webhook metadata only\ninside the host and never accepted from protocol input.\n\nProvider error output retains only bounded allowlisted fields. Provider request\nidentity accepts a bounded `x-request-id` or `traceparent` value without control\ncharacters.\n\n## Understand webhook ingress\n\nWebhook ingress is absent unless a secret file is configured. When enabled,\nthe host also requires a central connector-event endpoint.\n\nThe fixed route `/webhooks/twenty` requires timestamp, signature, and nonce\nheaders. Verification uses HMAC-SHA-256 over exact bytes:\n\n```text\n<decimal timestamp>:<raw request body>\n```\n\nThe timestamp must be within five minutes. The signature is 64 hexadecimal\ncharacters, and the nonce is 32 hexadecimal characters.\n\nThe host validates workspace ID, webhook UUID, RFC 3339 event time, event-name\nsyntax, and JSON object shape. A durable compare-and-swap store admits each\nnonce once, with a bounded 100,000-nonce window.\n\nAn accepted delivery becomes a deterministic AIP event, enters the durable\nevent log, then enters the central outbox. HTTP success reports whether central\ndelivery was newly queued or already present.\n\n## Respect the transport bounds\n\n| Boundary | Source value |\n|---|---:|\n| Connect timeout | 10 seconds |\n| Complete provider request timeout | 120 seconds |\n| Provider JSON body | 16 MiB |\n| Default provider response | 64 MiB |\n| Maximum configured response | 256 MiB |\n| Encoded URL | 128 KiB |\n| Query entries | 64 |\n| One encoded query value | 32 KiB |\n| Batch records | 200 |\n| Webhook body | 4 MiB |\n\nResponse reading is streaming but the AIP operation is not. The connector\nbuffers one bounded JSON response and rejects invalid JSON.\n\n## Know the maturity boundary\n\nThe reviewed source contains contract tests and a standalone host. Its generic\nimage verifier builds the Twenty host, but the pinned five-product Compose\nqualification topology does not include a Twenty service.\n\nLocal retained evidence may describe another exact Twenty run. It does not\nqualify an unspecified rebuilt artifact or a different workspace automatically.\n\nBefore adoption, qualify the exact host digest, Twenty deployment, workspace,\nschema, credentials, operation allowlist, webhook path, and failure topology.\n\n## Know what is excluded\n\nThe reviewed connector does not expose:\n\n- arbitrary REST paths or HTTP methods;\n- arbitrary GraphQL documents;\n- API-token creation or credential material in AIP;\n- file upload or attachment workflows;\n- application, workflow, calendar, email, or telephony surfaces outside the\n  fixed record and metadata catalogues;\n- provider transactions or multi-operation atomicity;\n- cancellation or streaming;\n- provider rollback, AIP compensation, or automatic reconciliation;\n- schema-specific validation of dynamic record bodies;\n- compatibility with an unrecorded Twenty revision.\n\n## Choose the next path\n\nStart with the connector catalogue for scope, then read the AIP execution model\nbefore sending Actions. Use the fleet guide for the standalone host, the error\nreference before implementing retries, and the upstream-baseline page when\nreviewing provider identity.\n\n## Related documentation\n\n- [Connector catalog](../README.md)\n- [How AIP works](../../getting-started/how-aip-works.md)\n- [Deploy the connector fleet](../../guides/deploy-connector-fleet.md)\n- [Errors and retry decisions](../../reference/errors.md)\n- [Connector upstream baselines](../upstream-baselines.md)\n",
    "text": "Twenty connector\n\nThe Twenty connector exposes a fixed workspace-aware REST surface as governed\nAIP capabilities. Use it to manage standard or custom records, inspect or\nchange selected workspace metadata, read generated OpenAPI documents, and\ningest signed Twenty webhook events.\n\nThe connector is not an arbitrary HTTP or GraphQL proxy. Provider paths,\noperation names, query keys, credential placement, request limits, approval,\nidempotency, retry, response handling, and webhook verification are fixed in\nsource.\n\nDecide whether it fits\n\n| Requirement | Fit |\n\n| Query standard and custom object records | Yes |\n| Create, batch upsert, update, soft-delete, destroy, restore, or merge records | Yes, through fixed operations |\n| Find duplicates or run provider-native group-by | Yes |\n| Manage object, field, view, layout, and webhook metadata | Yes, for twelve allowlisted resources |\n| Read workspace-specific core and metadata OpenAPI documents | Yes |\n| Receive signed Twenty webhook events through AIP | Yes, when ingress security and event delivery are configured |\n| Call arbitrary REST paths | No |\n| Execute arbitrary GraphQL | No |\n| Create or expose Twenty API keys | No |\n| Stream, cancel, transact, compensate, or automatically reconcile provider work | No |\n| Prove compatibility with any Twenty revision or deployment | No |\n\nChoose a separate, narrowly reviewed connector when an excluded provider\nsurface is required. Do not add a caller-selected path or credential to an\nAction.\n\nFix the reviewed identity\n\n| Property | Reviewed value |\n\n| AIP source | 97be86e9efedf07ecf1783b03800f683f107fb04 |\n| Connector crate | aip-connector-twenty 1.0.0 workspace line |\n| Standalone host | aip-host-twenty 1.0.0 workspace line |\n| Connector profile | aip.connector.twenty.v1 |\n| AIP protocol | 1.0 |\n| Upstream mapping revision | 96a24563674313a3071d359bfccaf33d5e130ab8 |\n| Operation catalogue | 22 fixed operations |\n| Metadata catalogue | 12 fixed resources |\n\nThe upstream commit is the mapping reference recorded by connector source. A\ndeployed Twenty image, edition, migration state, and workspace schema require\ntheir own identity and evidence.\n\nUnderstand the deployment boundary\n\nOne standalone aip-host-twenty process owns:\n• one AIP tenant, connector instance, and concrete replica;\n• one configured Twenty workspace UUID;\n• one fixed Twenty origin;\n• one owner-controlled API-token file;\n• one optional owner-controlled webhook-secret file;\n• one optional operation allowlist;\n• durable AIP runtime, replay, event, and outbox state;\n• native AIP signing, lifecycle, routing, and credential-revision policy.\n\nThe host receives signed AIP Actions and sends synchronous REST requests with a\nBearer header. It disables redirects and adds the AIP Action ID to provider\nrequests.\n\nKeep one host instance bound to one tenant and intended Twenty workspace. The\nworkspace UUID participates in deterministic create IDs, manifest identity,\nwebhook validation, and external-account routing.\n\nRead the capability groups\n\n| Group | Operations | Purpose |\n\n| Record query | 4 | List, get, find duplicates, and group records |\n| Record create and update | 4 | Create, create many, update, and update many |\n| Record lifecycle | 7 | Soft-delete, destroy, restore, and merge |\n| Metadata | 5 | List, get, create, update, and delete allowlisted resources |\n| OpenAPI | 2 | Read workspace core and metadata documents |\n\nCapability IDs use cap:twenty:, such as\ncap:twenty:record.list or cap:twenty:metadata.update.\n\nAn optional operations file can reduce the 22-operation catalogue. An empty\nallowlist is invalid. Deployment policy cannot introduce an unknown operation.\n\nUse the fixed record surface\n\nRecord Actions name an object matching\n^[A-Za-z][A-Za-z0-9]{0,127}$. This permits Twenty standard and custom object\nnames without allowing path separators or arbitrary provider routes.\n\nSingle-record operations require an RFC 4122 UUID version 1 through 5. Bulk\nupdate, soft-delete, destroy, and restore require a non-empty provider filter.\n\nCreate and create-many operations force Twenty upsert=true. When a body lacks\nan ID, the connector derives a deterministic UUID version 5 from workspace,\nidempotency key, and item index.\n\nAn explicit valid record UUID is preserved. Batch create accepts one through\n200 record objects.\n\nRestore-one uses Twenty's filtered collection restore route because the pinned\nprovider revision rejects the documented single-record restore path. The\nconnector injects an exact ID filter after validating the requested UUID.\n\nUse only allowlisted metadata\n\nThe metadata surface includes:\n• objects and fields;\n• views, viewFields, viewFilters, viewGroups, viewSorts, and\n  viewFilterGroups;\n• pageLayouts, pageLayoutTabs, and pageLayoutWidgets;\n• webhooks.\n\nEach list resource accepts only its provider-specific query keys. Page-layout\ntabs require pageLayoutId; widgets require pageLayoutTabId.\n\nWebhook metadata has an additional secret boundary. Action input cannot supply\nsecret. Create injects the configured host secret, and update injects it only\nwhen rotateConfiguredSecret is exactly true.\n\nThe connector recursively removes every secret key from webhook metadata\nresponses.\n\nApply governance by operation\n\n| Class | Count | Approval | Idempotency | Retry contract | Risk |\n\n| Reads | 8 | No connector-required approval | Optional | Safe | Low |\n| Create one or many, update one | 3 | Required | Required | Safe with key | High |\n| Other record mutations | 8 | Required | Required | Unsafe | High, except permanent destroy |\n| Metadata mutations | 3 | Required | Required | Unsafe | Critical |\n\nThe two permanent-destroy operations are also critical. Every mutation requires\ntenant-policy approval with reason, input snapshot, and policy decision.\nApproval expires after 15 minutes.\n\nMutation idempotency is scoped to the external account, uses input-hash\nrevalidation, and declares a seven-day contract TTL. The connector forwards the\nkey but does not provide a local provider-effect reconciliation API.\n\nAll operations are synchronous. The connector publishes no async, streaming,\ncancellation, transaction, reconciliation, or compensation support.\n\nInterpret retry safety narrowly\n\nThe eleven retry-safe operations are the eight reads plus create, create-many,\nand update-one. The create paths use deterministic IDs and force provider\nupsert.\n\nUpdate-many, deletes, restore, merge, and metadata mutations remain retry-unsafe.\nA 429 or 5xx response marks every mutation outcome uncertain, including a\nretry-safe mutation.\n\nTransport failure is retryable only when the operation contract permits it and\nthe connector can classify the failure safely. Reconcile the original Action\nand provider state before retrying any uncertain mutation.\n\nProtect data and credentials\n\nEvery capability declares confidential data, possible personal data, and\nrequired redaction. Record bodies, query filters, metadata, OpenAPI documents,\nwebhook payloads, and provider errors can expose workspace structure or customer\ndata.\n\nThe API token remains in an owner-controlled file and is used only as a Bearer\nheader. It must be UTF-8, at most 16 KiB, and contain no whitespace or DEL.\n\nThe webhook HMAC secret is separate. It is injected into webhook metadata only\ninside the host and never accepted from protocol input.\n\nProvider error output retains only bounded allowlisted fields. Provider request\nidentity accepts a bounded x-request-id or traceparent value without control\ncharacters.\n\nUnderstand webhook ingress\n\nWebhook ingress is absent unless a secret file is configured. When enabled,\nthe host also requires a central connector-event endpoint.\n\nThe fixed route /webhooks/twenty requires timestamp, signature, and nonce\nheaders. Verification uses HMAC-SHA-256 over exact bytes:\n\n:\n\nThe timestamp must be within five minutes. The signature is 64 hexadecimal\ncharacters, and the nonce is 32 hexadecimal characters.\n\nThe host validates workspace ID, webhook UUID, RFC 3339 event time, event-name\nsyntax, and JSON object shape. A durable compare-and-swap store admits each\nnonce once, with a bounded 100,000-nonce window.\n\nAn accepted delivery becomes a deterministic AIP event, enters the durable\nevent log, then enters the central outbox. HTTP success reports whether central\ndelivery was newly queued or already present.\n\nRespect the transport bounds\n\n| Boundary | Source value |\n\n| Connect timeout | 10 seconds |\n| Complete provider request timeout | 120 seconds |\n| Provider JSON body | 16 MiB |\n| Default provider response | 64 MiB |\n| Maximum configured response | 256 MiB |\n| Encoded URL | 128 KiB |\n| Query entries | 64 |\n| One encoded query value | 32 KiB |\n| Batch records | 200 |\n| Webhook body | 4 MiB |\n\nResponse reading is streaming but the AIP operation is not. The connector\nbuffers one bounded JSON response and rejects invalid JSON.\n\nKnow the maturity boundary\n\nThe reviewed source contains contract tests and a standalone host. Its generic\nimage verifier builds the Twenty host, but the pinned five-product Compose\nqualification topology does not include a Twenty service.\n\nLocal retained evidence may describe another exact Twenty run. It does not\nqualify an unspecified rebuilt artifact or a different workspace automatically.\n\nBefore adoption, qualify the exact host digest, Twenty deployment, workspace,\nschema, credentials, operation allowlist, webhook path, and failure topology.\n\nKnow what is excluded\n\nThe reviewed connector does not expose:\n• arbitrary REST paths or HTTP methods;\n• arbitrary GraphQL documents;\n• API-token creation or credential material in AIP;\n• file upload or attachment workflows;\n• application, workflow, calendar, email, or telephony surfaces outside the\n  fixed record and metadata catalogues;\n• provider transactions or multi-operation atomicity;\n• cancellation or streaming;\n• provider rollback, AIP compensation, or automatic reconciliation;\n• schema-specific validation of dynamic record bodies;\n• compatibility with an unrecorded Twenty revision.\n\nChoose the next path\n\nStart with the connector catalogue for scope, then read the AIP execution model\nbefore sending Actions. Use the fleet guide for the standalone host, the error\nreference before implementing retries, and the upstream-baseline page when\nreviewing provider identity.\n\nRelated documentation\n• Connector catalog (../README.md)\n• How AIP works (../../getting-started/how-aip-works.md)\n• Deploy the connector fleet (../../guides/deploy-connector-fleet.md)\n• Errors and retry decisions (../../reference/errors.md)\n• Connector upstream baselines (../upstream-baselines.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "222c77510a8aa1094f8a2171e9d008e2f20f4936f53dfe94a4a9d64545658d63"
  }
}