{
  "schemaVersion": "1.0",
  "title": "Twenty provider boundaries and exclusions",
  "description": "Use this reference to decide whether an intended integration belongs inside the reviewed Twenty connector. The connector is a fixed, workspace-aware mapping; it is not a generic transport for the complete provider API.",
  "canonical": "https://getaip.org/docs/connectors/twenty/reference/provider-boundaries-and-exclusions",
  "route": "/docs/connectors/twenty/reference/provider-boundaries-and-exclusions",
  "source": "docs/connectors/twenty/reference/provider-boundaries-and-exclusions.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/twenty/reference/provider-boundaries-and-exclusions.md",
    "txt": "/docs/download/connectors/twenty/reference/provider-boundaries-and-exclusions.txt",
    "json": "/docs/download/connectors/twenty/reference/provider-boundaries-and-exclusions.json",
    "pdf": "/docs/download/connectors/twenty/reference/provider-boundaries-and-exclusions.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Twenty provider boundaries and exclusions\ndescription: >-\n  Decide whether an integration fits the fixed Twenty operation, identity,\n  execution, data, webhook, and evidence boundary\nkind: reference\naudience: integrator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: twenty\n---\n\n# Twenty provider boundaries and exclusions\n\nUse this reference to decide whether an intended integration belongs inside the\nreviewed Twenty connector. The connector is a fixed, workspace-aware mapping;\nit is not a generic transport for the complete provider API.\n\nAn integration is in scope only when its operation, route, identity, data,\ngovernance, execution, and evidence needs fit the boundaries below.\n\n## Version boundary\n\n| Identity | Reviewed value |\n|---|---|\n| AIP source | `97be86e9efedf07ecf1783b03800f683f107fb04` |\n| Provider mapping source | `96a24563674313a3071d359bfccaf33d5e130ab8` |\n| Connector ID | `twenty` |\n| Connector profile | `aip.connector.twenty.v1` |\n| AIP workspace version | `1.0.0` |\n\nThe provider revision is the source identity from which the mapping was\nderived. It is not a runtime version negotiation, deployed-provider digest, or\nproof that a later provider release remains compatible.\n\nThe connector does not fetch, compile, or inspect the provider source at\nstartup. Live compatibility requires a separately identified deployment and\nevidence campaign.\n\n## Supported operation boundary\n\nThe closed catalogue contains:\n\n| Family | Operations |\n|---|---:|\n| Record query and aggregation | 4 |\n| Record create and update | 4 |\n| Record delete, restore, and merge | 7 |\n| Workspace metadata | 5 |\n| OpenAPI documents | 2 |\n| **Total** | **22** |\n\nAn optional host file can admit any non-empty subset. It cannot define a new\nsuffix, route, method, risk, schema, or contract.\n\nStandard and custom record objects share the same bounded object-name grammar.\nThat dynamic object selector does not make provider paths dynamic: every route\nstill comes from a fixed operation template.\n\nThe metadata selector is narrower. It accepts exactly twelve source-owned\nresource names.\n\n## Explicit API exclusions\n\nThe connector does not provide:\n\n- arbitrary REST methods or paths;\n- arbitrary GraphQL documents, variables, or operation names;\n- provider API-token creation, listing, rotation, or revocation;\n- arbitrary webhook endpoint forwarding;\n- caller-selected origins, workspaces, provider accounts, or credentials;\n- capability generation from an observed OpenAPI document;\n- every operation present in the upstream provider source;\n- a generic passthrough for unsupported record or metadata endpoints.\n\nDo not encode a missing path into `object`, `resource`, `id`, query, or body.\nThose fields are validated or appended within one fixed request template.\n\nAdd an operation through reviewed connector source, schema, tests, admission,\ndocumentation, and qualification. Do not weaken route validation to bypass the\ncatalogue.\n\n## Provider origin and authentication boundary\n\nThe host fixes one provider origin, one workspace UUID, and one API-token file\nwhen its process starts.\n\nThe origin:\n\n- contains no credentials, path prefix, query, or fragment;\n- requires HTTPS except for controlled loopback or explicitly allowed private HTTP;\n- must contain a host;\n- never follows redirects.\n\nThe connector sends the provider credential only as a Bearer header to a route\njoined to that origin. Action input cannot replace the token or destination.\n\nThe host validates AIP tenant and external-account metadata independently from\nthe provider workspace. Equality between external-account ID and workspace UUID\nis a deployment policy, not an automatic connector check.\n\n## Route and query boundary\n\nEvery record object must match:\n\n```text\n^[A-Za-z][A-Za-z0-9_]{0,127}$\n```\n\nEvery ID selected by the connector must be an RFC 4122 UUID version 1 through\n5. These validators exclude path separators and traversal but do not establish\nobject or record ownership.\n\nEach operation has a closed query-key set. Unknown keys and `null` values fail.\nArrays and objects are compact-JSON encoded into one provider query value; the\nconnector does not interpret provider filter or order syntax.\n\nThe connector does not provide automatic pagination, cursor iteration, field\nprojection, target-count estimation, provider query planning, or relationship\nexpansion beyond the admitted `depth` value.\n\n## Provider schema boundary\n\nOuter AIP schemas validate object, UUID, query, body shape, batch counts,\nduplicate alternatives, merge bounds, and selected metadata dependencies.\n\nThe connector does not validate arbitrary record or metadata body fields\nagainst the configured workspace schema. It also does not normalize provider\nrecord, metadata, OpenAPI, or error bodies into a stable cross-version model.\n\nThe two OpenAPI Resources can expose current provider descriptions. The\nconnector does not:\n\n- validate those documents as OpenAPI;\n- resolve references or calculate canonical digests;\n- reconcile them with the fixed mapping;\n- execute operations found in them;\n- turn observed fields into authorization policy.\n\nApplications must pin an observed schema digest and maintain object and field\nallowlists when workspace-specific bodies are consequential.\n\n## Execution boundary\n\nAll 22 operations are synchronous and non-streaming. The connector advertises\nno:\n\n- connector-managed asynchronous execution;\n- result or event streaming;\n- Action cancellation;\n- transaction planning or commit;\n- reconciliation operation;\n- compensation capability;\n- provider rollback.\n\nFourteen mutations declare `rollback_not_supported`. A separate provider\noperation, such as restore after soft delete, is a new governed intent rather\nthan an AIP compensation contract.\n\nThe host may receive lifecycle drain or shutdown controls. Those process\ncontrols do not make a dispatched provider mutation cancellable.\n\n## Approval, idempotency, and retry boundary\n\nAll fourteen mutations require tenant-policy approval and an\nexternal-account-scoped key. The approval window is 900,000 ms; the published\nkey TTL is 604,800,000 ms.\n\nThe connector advertises retry support for eight reads plus:\n\n- `record.create`;\n- `record.create_many`;\n- `record.update`.\n\nThose three writes are safe only with the original key and unchanged canonical\ninput. The other eleven mutations advertise unsafe retry.\n\nApproval does not validate provider schema or make an effect reversible. A key\ndoes not prove that every provider endpoint deduplicates requests. A retryable\nflag does not authorize a replacement Action.\n\n## Data and result boundary\n\nEvery capability declares confidential data, possible personal information,\nand required redaction. The connector returns decoded provider JSON inside:\n\n```json\n{\n  \"http_status\": 200,\n  \"provider_request_id\": null,\n  \"body\": {}\n}\n```\n\nIt does not apply a general field-redaction policy to successful record,\nmetadata, or OpenAPI bodies. The special `webhooks` metadata path recursively\nremoves fields named `secret`.\n\nProvider error projection retains only bounded `statusCode`, `error`,\n`message`, `messages`, and `code` fields. It omits other provider error data.\n\nThe connector does not own tenant retention, data residency, legal hold,\nfield-level authorization, application output minimization, or evidence access\npolicy.\n\n## Size and timeout boundary\n\n| Boundary | Reviewed value |\n|---|---:|\n| Connect timeout | 10 seconds |\n| Total provider request timeout | 120 seconds |\n| Provider request JSON | 16 MiB |\n| Provider response default | 64 MiB |\n| Provider response maximum | 256 MiB |\n| Encoded query value | 32 KiB |\n| Encoded provider URL | 128 KiB |\n| Record batch | 200 records |\n| Webhook body | 4 MiB |\n\nRaising the configurable response ceiling does not change other limits. The\nconnector does not split oversized requests or return partial oversized\nresponses.\n\n## Webhook boundary\n\nThe host optionally exposes one fixed route, `/webhooks/twenty`, backed by one\nstartup-loaded HMAC secret and one configured workspace.\n\nIt requires exact timestamp, signature, and nonce headers; validates HMAC over\ntimestamp, colon, and raw body; fences the nonce; matches payload workspace;\nmaps one deterministic event; and durably queues central publication.\n\nThe ingress does not:\n\n- accept an Action-provided secret;\n- accept another workspace under the same binding;\n- define a source-owned event-name enum;\n- redact the complete provider event payload;\n- guarantee central acknowledgement before every HTTP `200`;\n- make same-nonce replay safe after a late local failure.\n\nProvider webhook registration is a separate critical metadata mutation. A\nmatching registration does not prove ingress, replay, storage, or publication.\n\n## Error and recovery boundary\n\nThe connector categorizes authentication, remote temporary, remote rejection,\ntransport, storage, invalid response, and invalid request failures.\n\nMutation uncertainty can arise after dispatch even when a concrete provider\nresult is unavailable. The connector exposes no automatic provider-state\nlookup or reconciliation contract.\n\nRecovery must retain the original Action, key, approval, provider request\nidentity, output, and receipts. Use a bounded authorized read before another\nmutation. Do not erase uncertainty by assigning a new identity.\n\n## Deployment and topology boundary\n\nThe repository contains a standalone `aip-host-twenty` binary and generic host\nimage support. The reviewed five-product connector-fleet Compose topology does\nnot contain a Twenty service.\n\nTherefore:\n\n- the connector source is deployable through the shared host architecture;\n- the pinned topology does not provide a source-owned Twenty local quickstart;\n- a separate deployment must define origin, workspace, secrets, database,\n  identities, registry admission, ingress, and operations;\n- another topology requires its own immutable artifact and evidence identity.\n\nDo not infer deployment or qualification from compilation support alone.\n\n## Evidence boundary\n\nSource review can establish implemented operations and guards. It cannot by\nitself establish:\n\n- a deployed provider version or workspace schema;\n- exact host image digest or admitted registry row;\n- current route eligibility and credential status;\n- successful record, metadata, OpenAPI, or webhook execution;\n- multi-replica replay or outbox recovery;\n- production readiness or live compatibility.\n\nQualification claims must name the exact source, artifact, topology, provider,\nworkspace, test procedure, results, retained evidence, and limitations.\n\n## Decide how to handle an out-of-scope need\n\n| Need | Correct response |\n|---|---|\n| A missing fixed provider operation | Add and review a typed connector operation |\n| Arbitrary GraphQL | Build a separately governed connector; do not tunnel it through this mapping |\n| Dynamic provider path | Define a bounded route and schema in source |\n| API-token lifecycle | Use provider and deployment secret-management procedures |\n| Asynchronous or streaming workflow | Design an explicit AIP contract and implementation before advertising it |\n| Cancellation or transaction semantics | Add source-owned protocol behavior and provider evidence; do not infer it |\n| Automatic schema adaptation | Build a reviewed generator and compatibility gate outside current claims |\n| Unsupported live provider revision | Re-pin, review drift, test, qualify, and update evidence |\n\n## Related documentation\n\n- [Twenty connector overview](../README.md)\n- [Twenty capability index](../capabilities/README.md)\n- [Twenty OpenAPI documents](../capabilities/openapi-documents.md)\n- [Twenty webhook security, replay, and events](webhook-security-replay-and-events.md)\n- [Connector upstream baselines](../../upstream-baselines.md)\n",
    "text": "Twenty provider boundaries and exclusions\n\nUse this reference to decide whether an intended integration belongs inside the\nreviewed Twenty connector. The connector is a fixed, workspace-aware mapping;\nit is not a generic transport for the complete provider API.\n\nAn integration is in scope only when its operation, route, identity, data,\ngovernance, execution, and evidence needs fit the boundaries below.\n\nVersion boundary\n\n| Identity | Reviewed value |\n\n| AIP source | 97be86e9efedf07ecf1783b03800f683f107fb04 |\n| Provider mapping source | 96a24563674313a3071d359bfccaf33d5e130ab8 |\n| Connector ID | twenty |\n| Connector profile | aip.connector.twenty.v1 |\n| AIP workspace version | 1.0.0 |\n\nThe provider revision is the source identity from which the mapping was\nderived. It is not a runtime version negotiation, deployed-provider digest, or\nproof that a later provider release remains compatible.\n\nThe connector does not fetch, compile, or inspect the provider source at\nstartup. Live compatibility requires a separately identified deployment and\nevidence campaign.\n\nSupported operation boundary\n\nThe closed catalogue contains:\n\n| Family | Operations |\n\n| Record query and aggregation | 4 |\n| Record create and update | 4 |\n| Record delete, restore, and merge | 7 |\n| Workspace metadata | 5 |\n| OpenAPI documents | 2 |\n| Total | 22 |\n\nAn optional host file can admit any non-empty subset. It cannot define a new\nsuffix, route, method, risk, schema, or contract.\n\nStandard and custom record objects share the same bounded object-name grammar.\nThat dynamic object selector does not make provider paths dynamic: every route\nstill comes from a fixed operation template.\n\nThe metadata selector is narrower. It accepts exactly twelve source-owned\nresource names.\n\nExplicit API exclusions\n\nThe connector does not provide:\n• arbitrary REST methods or paths;\n• arbitrary GraphQL documents, variables, or operation names;\n• provider API-token creation, listing, rotation, or revocation;\n• arbitrary webhook endpoint forwarding;\n• caller-selected origins, workspaces, provider accounts, or credentials;\n• capability generation from an observed OpenAPI document;\n• every operation present in the upstream provider source;\n• a generic passthrough for unsupported record or metadata endpoints.\n\nDo not encode a missing path into object, resource, id, query, or body.\nThose fields are validated or appended within one fixed request template.\n\nAdd an operation through reviewed connector source, schema, tests, admission,\ndocumentation, and qualification. Do not weaken route validation to bypass the\ncatalogue.\n\nProvider origin and authentication boundary\n\nThe host fixes one provider origin, one workspace UUID, and one API-token file\nwhen its process starts.\n\nThe origin:\n• contains no credentials, path prefix, query, or fragment;\n• requires HTTPS except for controlled loopback or explicitly allowed private HTTP;\n• must contain a host;\n• never follows redirects.\n\nThe connector sends the provider credential only as a Bearer header to a route\njoined to that origin. Action input cannot replace the token or destination.\n\nThe host validates AIP tenant and external-account metadata independently from\nthe provider workspace. Equality between external-account ID and workspace UUID\nis a deployment policy, not an automatic connector check.\n\nRoute and query boundary\n\nEvery record object must match:\n\n^[A-Za-z][A-Za-z0-9]{0,127}$\n\nEvery ID selected by the connector must be an RFC 4122 UUID version 1 through\n5. These validators exclude path separators and traversal but do not establish\nobject or record ownership.\n\nEach operation has a closed query-key set. Unknown keys and null values fail.\nArrays and objects are compact-JSON encoded into one provider query value; the\nconnector does not interpret provider filter or order syntax.\n\nThe connector does not provide automatic pagination, cursor iteration, field\nprojection, target-count estimation, provider query planning, or relationship\nexpansion beyond the admitted depth value.\n\nProvider schema boundary\n\nOuter AIP schemas validate object, UUID, query, body shape, batch counts,\nduplicate alternatives, merge bounds, and selected metadata dependencies.\n\nThe connector does not validate arbitrary record or metadata body fields\nagainst the configured workspace schema. It also does not normalize provider\nrecord, metadata, OpenAPI, or error bodies into a stable cross-version model.\n\nThe two OpenAPI Resources can expose current provider descriptions. The\nconnector does not:\n• validate those documents as OpenAPI;\n• resolve references or calculate canonical digests;\n• reconcile them with the fixed mapping;\n• execute operations found in them;\n• turn observed fields into authorization policy.\n\nApplications must pin an observed schema digest and maintain object and field\nallowlists when workspace-specific bodies are consequential.\n\nExecution boundary\n\nAll 22 operations are synchronous and non-streaming. The connector advertises\nno:\n• connector-managed asynchronous execution;\n• result or event streaming;\n• Action cancellation;\n• transaction planning or commit;\n• reconciliation operation;\n• compensation capability;\n• provider rollback.\n\nFourteen mutations declare rollbacknotsupported. A separate provider\noperation, such as restore after soft delete, is a new governed intent rather\nthan an AIP compensation contract.\n\nThe host may receive lifecycle drain or shutdown controls. Those process\ncontrols do not make a dispatched provider mutation cancellable.\n\nApproval, idempotency, and retry boundary\n\nAll fourteen mutations require tenant-policy approval and an\nexternal-account-scoped key. The approval window is 900,000 ms; the published\nkey TTL is 604,800,000 ms.\n\nThe connector advertises retry support for eight reads plus:\n• record.create;\n• record.createmany;\n• record.update.\n\nThose three writes are safe only with the original key and unchanged canonical\ninput. The other eleven mutations advertise unsafe retry.\n\nApproval does not validate provider schema or make an effect reversible. A key\ndoes not prove that every provider endpoint deduplicates requests. A retryable\nflag does not authorize a replacement Action.\n\nData and result boundary\n\nEvery capability declares confidential data, possible personal information,\nand required redaction. The connector returns decoded provider JSON inside:\n\n{\n  \"httpstatus\": 200,\n  \"providerrequestid\": null,\n  \"body\": {}\n}\n\nIt does not apply a general field-redaction policy to successful record,\nmetadata, or OpenAPI bodies. The special webhooks metadata path recursively\nremoves fields named secret.\n\nProvider error projection retains only bounded statusCode, error,\nmessage, messages, and code fields. It omits other provider error data.\n\nThe connector does not own tenant retention, data residency, legal hold,\nfield-level authorization, application output minimization, or evidence access\npolicy.\n\nSize and timeout boundary\n\n| Boundary | Reviewed value |\n\n| Connect timeout | 10 seconds |\n| Total provider request timeout | 120 seconds |\n| Provider request JSON | 16 MiB |\n| Provider response default | 64 MiB |\n| Provider response maximum | 256 MiB |\n| Encoded query value | 32 KiB |\n| Encoded provider URL | 128 KiB |\n| Record batch | 200 records |\n| Webhook body | 4 MiB |\n\nRaising the configurable response ceiling does not change other limits. The\nconnector does not split oversized requests or return partial oversized\nresponses.\n\nWebhook boundary\n\nThe host optionally exposes one fixed route, /webhooks/twenty, backed by one\nstartup-loaded HMAC secret and one configured workspace.\n\nIt requires exact timestamp, signature, and nonce headers; validates HMAC over\ntimestamp, colon, and raw body; fences the nonce; matches payload workspace;\nmaps one deterministic event; and durably queues central publication.\n\nThe ingress does not:\n• accept an Action-provided secret;\n• accept another workspace under the same binding;\n• define a source-owned event-name enum;\n• redact the complete provider event payload;\n• guarantee central acknowledgement before every HTTP 200;\n• make same-nonce replay safe after a late local failure.\n\nProvider webhook registration is a separate critical metadata mutation. A\nmatching registration does not prove ingress, replay, storage, or publication.\n\nError and recovery boundary\n\nThe connector categorizes authentication, remote temporary, remote rejection,\ntransport, storage, invalid response, and invalid request failures.\n\nMutation uncertainty can arise after dispatch even when a concrete provider\nresult is unavailable. The connector exposes no automatic provider-state\nlookup or reconciliation contract.\n\nRecovery must retain the original Action, key, approval, provider request\nidentity, output, and receipts. Use a bounded authorized read before another\nmutation. Do not erase uncertainty by assigning a new identity.\n\nDeployment and topology boundary\n\nThe repository contains a standalone aip-host-twenty binary and generic host\nimage support. The reviewed five-product connector-fleet Compose topology does\nnot contain a Twenty service.\n\nTherefore:\n• the connector source is deployable through the shared host architecture;\n• the pinned topology does not provide a source-owned Twenty local quickstart;\n• a separate deployment must define origin, workspace, secrets, database,\n  identities, registry admission, ingress, and operations;\n• another topology requires its own immutable artifact and evidence identity.\n\nDo not infer deployment or qualification from compilation support alone.\n\nEvidence boundary\n\nSource review can establish implemented operations and guards. It cannot by\nitself establish:\n• a deployed provider version or workspace schema;\n• exact host image digest or admitted registry row;\n• current route eligibility and credential status;\n• successful record, metadata, OpenAPI, or webhook execution;\n• multi-replica replay or outbox recovery;\n• production readiness or live compatibility.\n\nQualification claims must name the exact source, artifact, topology, provider,\nworkspace, test procedure, results, retained evidence, and limitations.\n\nDecide how to handle an out-of-scope need\n\n| Need | Correct response |\n\n| A missing fixed provider operation | Add and review a typed connector operation |\n| Arbitrary GraphQL | Build a separately governed connector; do not tunnel it through this mapping |\n| Dynamic provider path | Define a bounded route and schema in source |\n| API-token lifecycle | Use provider and deployment secret-management procedures |\n| Asynchronous or streaming workflow | Design an explicit AIP contract and implementation before advertising it |\n| Cancellation or transaction semantics | Add source-owned protocol behavior and provider evidence; do not infer it |\n| Automatic schema adaptation | Build a reviewed generator and compatibility gate outside current claims |\n| Unsupported live provider revision | Re-pin, review drift, test, qualify, and update evidence |\n\nRelated documentation\n• Twenty connector overview (../README.md)\n• Twenty capability index (../capabilities/README.md)\n• Twenty OpenAPI documents (../capabilities/openapi-documents.md)\n• Twenty webhook security, replay, and events (webhook-security-replay-and-events.md)\n• Connector upstream baselines (../../upstream-baselines.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "3f07884529d92e134831b1ca25d96d39d8a031fbe7cc5d10872502722683463f"
  }
}