{
  "schemaVersion": "1.0",
  "title": "Cal.diy operator-only and excluded routes",
  "description": "Use this reference when a Cal.diy provider route has no corresponding AIP capability. It distinguishes deliberate control-plane exclusions from the 81 published business operations and maps two deprecated aliases to their canonical capabili",
  "canonical": "https://getaip.org/docs/connectors/cal-diy/reference/operator-only-and-excluded-routes",
  "route": "/docs/connectors/cal-diy/reference/operator-only-and-excluded-routes",
  "source": "docs/connectors/cal-diy/reference/operator-only-and-excluded-routes.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/cal-diy/reference/operator-only-and-excluded-routes.md",
    "txt": "/docs/download/connectors/cal-diy/reference/operator-only-and-excluded-routes.txt",
    "json": "/docs/download/connectors/cal-diy/reference/operator-only-and-excluded-routes.json",
    "pdf": "/docs/download/connectors/cal-diy/reference/operator-only-and-excluded-routes.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Cal.diy operator-only and excluded routes\ndescription: Identify deliberate control-plane exclusions and migrate away from deprecated provider aliases\nkind: reference\naudience: connector-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: cal-diy\n---\n\n# Cal.diy operator-only and excluded routes\n\nUse this reference when a Cal.diy provider route has no corresponding AIP\ncapability. It distinguishes deliberate control-plane exclusions from the 81\npublished business operations and maps two deprecated aliases to their\ncanonical capabilities.\n\nAn excluded route is not a hidden capability. The connector host does not mount\nan operator API for it, and the business-operation client has no catch-all path.\nDo not call the provider directly with connector credentials to bypass this\nboundary.\n\n## Pinned inventory\n\n| Inventory | Entries | Published as AIP capabilities |\n|---|---:|---:|\n| Business operations | 81 | Yes |\n| Operator-only excluded method-path pairs | 38 | No |\n| Deprecated alias method-path pairs | 2 | No |\n| **Audited total** | **121** | **81** |\n\nAt source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`, tests require all 40 excluded pairs\nto be unique and disjoint from every published method-path pair.\n\nThe source-pinned Cal.diy upstream revision is\n`f00434927386c9ecdcbd7e6c5f82d22044a245bc`. A later upstream or connector\nrevision requires a fresh inventory; this page is not a claim about every route\nin a current provider deployment.\n\n## Interpret the boundary\n\n| Term | Meaning here |\n|---|---|\n| Published | Has a fixed `CalDiyOperation`, capability id, schema, contract, route, version, and governed dispatch path |\n| Operator-only | Deliberately omitted because it provisions or rotates credentials, establishes an external connection or browser session, administers OAuth clients, or verifies resource ownership |\n| Deprecated alias | Older provider path omitted in favor of one canonical published route with the same intended provider semantics |\n| Unknown | Neither published nor in this pinned exclusion inventory; do not infer support or safety |\n\n`Operator-only` describes the trust plane that should own the provider action.\nIt does not mean `aip-host-cal-diy` exposes these paths to a privileged caller.\n\nThe excluded entries have no connector-owned input schema, risk level, approval\npolicy, idempotency scope, API-version selection, request partition, response\nschema, reconciliation path, or qualification claim. Do not copy those details\nfrom a neighboring public capability.\n\n## Decide what to do when a capability is absent\n\n1. Search the admitted capability catalog for the intended business outcome,\n   not for a provider URL fragment.\n2. If a published capability exists, use its exact schema and contract.\n3. If the route appears below, stop the agent workflow and hand the task to a\n   separately authenticated provider or product operator process.\n4. If the route is a deprecated alias, migrate to the named canonical\n   capability.\n5. If it appears nowhere, treat it as unsupported at this revision.\n6. Propose a connector change only after deciding that the outcome belongs in\n   the business trust plane rather than the credential or ownership plane.\n\nAn unknown capability id fails before provider dispatch as\n`connector.cal_diy.invalid_action`. Changing the capability id to resemble an\nupstream path cannot create a route.\n\n## Why HTTP methods do not define safety\n\nThe operator-only inventory contains 18 `GET`, 13 `POST`, 4 `DELETE`, and 3\n`PATCH` pairs. Several `GET` paths contain `connect`, `save`, `callback`, or\nsimilar session-establishment language. Treat the route purpose and trust\nboundary as authoritative; do not assume an excluded `GET` is a harmless read.\n\nThe category labels below explain why a route is grouped. The method-path pairs\nremain the exact source inventory.\n\n## OAuth-client administration routes\n\nThese 18 routes create, inspect, change, refresh, or delete OAuth clients and\ntheir delegated users or webhooks. They can alter broad credential and\ndelegation state and remain outside agent-callable business operations.\n\n| Method | Provider path |\n|---|---|\n| `DELETE` | `/v2/oauth-clients/{client_id}` |\n| `DELETE` | `/v2/oauth-clients/{client_id}/users/{user_id}` |\n| `DELETE` | `/v2/oauth-clients/{client_id}/webhooks` |\n| `DELETE` | `/v2/oauth-clients/{client_id}/webhooks/{webhook_id}` |\n| `GET` | `/v2/auth/oauth2/clients/{client_id}` |\n| `GET` | `/v2/oauth-clients` |\n| `GET` | `/v2/oauth-clients/{client_id}` |\n| `GET` | `/v2/oauth-clients/{client_id}/users` |\n| `GET` | `/v2/oauth-clients/{client_id}/users/{user_id}` |\n| `GET` | `/v2/oauth-clients/{client_id}/webhooks` |\n| `GET` | `/v2/oauth-clients/{client_id}/webhooks/{webhook_id}` |\n| `PATCH` | `/v2/oauth-clients/{client_id}` |\n| `PATCH` | `/v2/oauth-clients/{client_id}/users/{user_id}` |\n| `PATCH` | `/v2/oauth-clients/{client_id}/webhooks/{webhook_id}` |\n| `POST` | `/v2/oauth-clients` |\n| `POST` | `/v2/oauth-clients/{client_id}/users` |\n| `POST` | `/v2/oauth-clients/{client_id}/users/{user_id}/force-refresh` |\n| `POST` | `/v2/oauth-clients/{client_id}/webhooks` |\n\nThe standalone host can authenticate outbound business requests with one\ndeployment-selected Bearer value or Cal platform client pair. That does not\nmake OAuth-client administration a public connector capability.\n\n## Credential, session, and connection routes\n\nThese 12 routes mint or refresh credentials, establish calendar, conferencing,\nor Stripe connections, or save connection state. Browser redirects, callbacks,\ncredential custody, and product administration belong outside the business\naction plane.\n\n| Method | Provider path |\n|---|---|\n| `GET` | `/v2/calendars/{calendar}/connect` |\n| `GET` | `/v2/calendars/{calendar}/save` |\n| `GET` | `/v2/conferencing/{app}/oauth/auth-url` |\n| `GET` | `/v2/conferencing/{app}/oauth/callback` |\n| `GET` | `/v2/stripe/check` |\n| `GET` | `/v2/stripe/connect` |\n| `GET` | `/v2/stripe/save` |\n| `POST` | `/v2/api-keys/refresh` |\n| `POST` | `/v2/auth/oauth2/token` |\n| `POST` | `/v2/calendars/ics-feed/save` |\n| `POST` | `/v2/calendars/{calendar}/credentials` |\n| `POST` | `/v2/oauth/{provider}/refresh` |\n\nPublic calendar and conferencing capabilities can inspect or use connections\nthat already exist. They do not grant permission to create browser sessions,\nsave credentials, refresh provider tokens, or connect a financial account.\n\n## Verified-resource ownership routes\n\nThese eight routes list verified email or phone resources or request and submit\nownership codes. Verification can establish identity and authority outside the\nconnector's tenant-bound business input, so it remains operator-owned.\n\n| Method | Provider path |\n|---|---|\n| `GET` | `/v2/verified-resources/emails` |\n| `GET` | `/v2/verified-resources/emails/{resource_id}` |\n| `GET` | `/v2/verified-resources/phones` |\n| `GET` | `/v2/verified-resources/phones/{resource_id}` |\n| `POST` | `/v2/verified-resources/emails/verification-code/request` |\n| `POST` | `/v2/verified-resources/emails/verification-code/verify` |\n| `POST` | `/v2/verified-resources/phones/verification-code/request` |\n| `POST` | `/v2/verified-resources/phones/verification-code/verify` |\n\nDo not place verification codes, ownership proofs, or provider-administration\ncredentials in an AIP business action merely to reach these routes.\n\n## Deprecated calendar-event aliases\n\nThe pinned upstream inventory included two singular `/event/` aliases. The\nconnector publishes only the plural `/events/` routes.\n\n| Excluded alias | Canonical capability | Canonical provider path |\n|---|---|---|\n| `GET /v2/calendars/{calendar}/event/{event_uid}` | `cap:cal_diy:calendar.event.get` | `GET /v2/calendars/{calendar}/events/{event_uid}` |\n| `PATCH /v2/calendars/{calendar}/event/{event_uid}` | `cap:cal_diy:calendar.event.update` | `PATCH /v2/calendars/{calendar}/events/{event_uid}` |\n\nApplications should migrate by selecting the canonical capability and its\npublished input schema. Do not rewrite a direct provider request by changing\nonly `event` to `events`: AIP identity, approval, idempotency, tenant routing,\nand durable result handling still apply. The update capability is a governed\nmutation; the get capability is a governed read.\n\n## Handle an operator workflow separately\n\nIf a deployment legitimately needs an excluded provider function, keep it\noutside the business connector and define a separate operator-owned workflow\nwith its own:\n\n- authenticated human or administrative service identity;\n- least-privilege provider credential and explicit secret custody;\n- browser state and callback validation where a session is involved;\n- ownership-proof handling and restricted audit evidence;\n- change approval, rotation, incident, and revocation procedure;\n- provider-specific versioning, validation, and recovery behavior.\n\nThis page does not define such an operator API or authorize a particular direct\nprovider call. The provider's current administrative documentation and the\ndeployment's security policy own that separate workflow.\n\n## Review a proposed connector expansion\n\nMoving a route into the business surface is a protocol-facing security change,\nnot an inventory edit. Review all of the following together:\n\n1. explain the user outcome and why it belongs outside the operator plane;\n2. pin the exact upstream revision, method, version, and canonical path;\n3. define one bounded capability id and closed input and output schemas;\n4. partition path, query, and body fields without arbitrary pass-through;\n5. classify data, PII, side effects, risk, and credential scope;\n6. define approval, idempotency, transaction, compensation, and reconciliation;\n7. keep provider credentials, verification codes, and raw secrets out of input;\n8. add positive, negative, boundary, restart, and provider-contract tests;\n9. remove the exact pair from the exclusion inventory and preserve uniqueness\n   and disjointness checks;\n10. regenerate capability metadata, update public documentation, and qualify the\n    exact artifact before making a live claim.\n\nDo not add a generic method-plus-path capability. That would erase the fixed\nschema, policy, credential, and audit boundary established by the connector.\n\n## Audit the exclusion boundary\n\n| Check | Expected result at this revision |\n|---|---|\n| Published capability ids | 81 unique ids |\n| Operator-only inventory | 38 unique method-path pairs |\n| Deprecated alias inventory | 2 unique method-path pairs |\n| Combined excluded inventory | 40 unique pairs |\n| Published versus excluded pairs | Disjoint |\n| Manifest compatibility metadata | `operator_only_routes_excluded: 38`; `deprecated_aliases_excluded: 2` |\n| Unknown capability invocation | Rejected before provider dispatch |\n| Arbitrary provider proxy | Absent |\n\nThese checks establish an implementation boundary. They do not show that a\ncurrent provider deployment exposes, removes, or preserves any excluded route.\n\n## Security and evidence boundaries\n\n- Provider-route discovery is not permission to invoke the route.\n- A provider `GET` verb is not evidence that a control-plane action is read-only.\n- Connector credentials must not be reused as a general provider admin token.\n- An excluded route has no inherited AIP approval or idempotency guarantee.\n- A deprecated alias has no compatibility promise from this connector.\n- Source tests prove inventory separation, not live provider behavior.\n\n## Related documentation\n\n- [API versions and public provider routes](api-versions-and-provider-routes.md)\n- [Cal.diy capability index](../capabilities/README.md)\n- [Pinned upstream baselines](../../upstream-baselines.md)\n- [Connector contract](../../../spec/connector-contract.md)\n- [Build a connector](../../../guides/build-a-connector.md)\n",
    "text": "Cal.diy operator-only and excluded routes\n\nUse this reference when a Cal.diy provider route has no corresponding AIP\ncapability. It distinguishes deliberate control-plane exclusions from the 81\npublished business operations and maps two deprecated aliases to their\ncanonical capabilities.\n\nAn excluded route is not a hidden capability. The connector host does not mount\nan operator API for it, and the business-operation client has no catch-all path.\nDo not call the provider directly with connector credentials to bypass this\nboundary.\n\nPinned inventory\n\n| Inventory | Entries | Published as AIP capabilities |\n\n| Business operations | 81 | Yes |\n| Operator-only excluded method-path pairs | 38 | No |\n| Deprecated alias method-path pairs | 2 | No |\n| Audited total | 121 | 81 |\n\nAt source revision\n97be86e9efedf07ecf1783b03800f683f107fb04, tests require all 40 excluded pairs\nto be unique and disjoint from every published method-path pair.\n\nThe source-pinned Cal.diy upstream revision is\nf00434927386c9ecdcbd7e6c5f82d22044a245bc. A later upstream or connector\nrevision requires a fresh inventory; this page is not a claim about every route\nin a current provider deployment.\n\nInterpret the boundary\n\n| Term | Meaning here |\n\n| Published | Has a fixed CalDiyOperation, capability id, schema, contract, route, version, and governed dispatch path |\n| Operator-only | Deliberately omitted because it provisions or rotates credentials, establishes an external connection or browser session, administers OAuth clients, or verifies resource ownership |\n| Deprecated alias | Older provider path omitted in favor of one canonical published route with the same intended provider semantics |\n| Unknown | Neither published nor in this pinned exclusion inventory; do not infer support or safety |\n\nOperator-only describes the trust plane that should own the provider action.\nIt does not mean aip-host-cal-diy exposes these paths to a privileged caller.\n\nThe excluded entries have no connector-owned input schema, risk level, approval\npolicy, idempotency scope, API-version selection, request partition, response\nschema, reconciliation path, or qualification claim. Do not copy those details\nfrom a neighboring public capability.\n\nDecide what to do when a capability is absent\n1. Search the admitted capability catalog for the intended business outcome,\n   not for a provider URL fragment.\n2. If a published capability exists, use its exact schema and contract.\n3. If the route appears below, stop the agent workflow and hand the task to a\n   separately authenticated provider or product operator process.\n4. If the route is a deprecated alias, migrate to the named canonical\n   capability.\n5. If it appears nowhere, treat it as unsupported at this revision.\n6. Propose a connector change only after deciding that the outcome belongs in\n   the business trust plane rather than the credential or ownership plane.\n\nAn unknown capability id fails before provider dispatch as\nconnector.caldiy.invalidaction. Changing the capability id to resemble an\nupstream path cannot create a route.\n\nWhy HTTP methods do not define safety\n\nThe operator-only inventory contains 18 GET, 13 POST, 4 DELETE, and 3\nPATCH pairs. Several GET paths contain connect, save, callback, or\nsimilar session-establishment language. Treat the route purpose and trust\nboundary as authoritative; do not assume an excluded GET is a harmless read.\n\nThe category labels below explain why a route is grouped. The method-path pairs\nremain the exact source inventory.\n\nOAuth-client administration routes\n\nThese 18 routes create, inspect, change, refresh, or delete OAuth clients and\ntheir delegated users or webhooks. They can alter broad credential and\ndelegation state and remain outside agent-callable business operations.\n\n| Method | Provider path |\n\n| DELETE | /v2/oauth-clients/{clientid} |\n| DELETE | /v2/oauth-clients/{clientid}/users/{userid} |\n| DELETE | /v2/oauth-clients/{clientid}/webhooks |\n| DELETE | /v2/oauth-clients/{clientid}/webhooks/{webhookid} |\n| GET | /v2/auth/oauth2/clients/{clientid} |\n| GET | /v2/oauth-clients |\n| GET | /v2/oauth-clients/{clientid} |\n| GET | /v2/oauth-clients/{clientid}/users |\n| GET | /v2/oauth-clients/{clientid}/users/{userid} |\n| GET | /v2/oauth-clients/{clientid}/webhooks |\n| GET | /v2/oauth-clients/{clientid}/webhooks/{webhookid} |\n| PATCH | /v2/oauth-clients/{clientid} |\n| PATCH | /v2/oauth-clients/{clientid}/users/{userid} |\n| PATCH | /v2/oauth-clients/{clientid}/webhooks/{webhookid} |\n| POST | /v2/oauth-clients |\n| POST | /v2/oauth-clients/{clientid}/users |\n| POST | /v2/oauth-clients/{clientid}/users/{userid}/force-refresh |\n| POST | /v2/oauth-clients/{clientid}/webhooks |\n\nThe standalone host can authenticate outbound business requests with one\ndeployment-selected Bearer value or Cal platform client pair. That does not\nmake OAuth-client administration a public connector capability.\n\nCredential, session, and connection routes\n\nThese 12 routes mint or refresh credentials, establish calendar, conferencing,\nor Stripe connections, or save connection state. Browser redirects, callbacks,\ncredential custody, and product administration belong outside the business\naction plane.\n\n| Method | Provider path |\n\n| GET | /v2/calendars/{calendar}/connect |\n| GET | /v2/calendars/{calendar}/save |\n| GET | /v2/conferencing/{app}/oauth/auth-url |\n| GET | /v2/conferencing/{app}/oauth/callback |\n| GET | /v2/stripe/check |\n| GET | /v2/stripe/connect |\n| GET | /v2/stripe/save |\n| POST | /v2/api-keys/refresh |\n| POST | /v2/auth/oauth2/token |\n| POST | /v2/calendars/ics-feed/save |\n| POST | /v2/calendars/{calendar}/credentials |\n| POST | /v2/oauth/{provider}/refresh |\n\nPublic calendar and conferencing capabilities can inspect or use connections\nthat already exist. They do not grant permission to create browser sessions,\nsave credentials, refresh provider tokens, or connect a financial account.\n\nVerified-resource ownership routes\n\nThese eight routes list verified email or phone resources or request and submit\nownership codes. Verification can establish identity and authority outside the\nconnector's tenant-bound business input, so it remains operator-owned.\n\n| Method | Provider path |\n\n| GET | /v2/verified-resources/emails |\n| GET | /v2/verified-resources/emails/{resourceid} |\n| GET | /v2/verified-resources/phones |\n| GET | /v2/verified-resources/phones/{resourceid} |\n| POST | /v2/verified-resources/emails/verification-code/request |\n| POST | /v2/verified-resources/emails/verification-code/verify |\n| POST | /v2/verified-resources/phones/verification-code/request |\n| POST | /v2/verified-resources/phones/verification-code/verify |\n\nDo not place verification codes, ownership proofs, or provider-administration\ncredentials in an AIP business action merely to reach these routes.\n\nDeprecated calendar-event aliases\n\nThe pinned upstream inventory included two singular /event/ aliases. The\nconnector publishes only the plural /events/ routes.\n\n| Excluded alias | Canonical capability | Canonical provider path |\n\n| GET /v2/calendars/{calendar}/event/{eventuid} | cap:caldiy:calendar.event.get | GET /v2/calendars/{calendar}/events/{eventuid} |\n| PATCH /v2/calendars/{calendar}/event/{eventuid} | cap:caldiy:calendar.event.update | PATCH /v2/calendars/{calendar}/events/{eventuid} |\n\nApplications should migrate by selecting the canonical capability and its\npublished input schema. Do not rewrite a direct provider request by changing\nonly event to events: AIP identity, approval, idempotency, tenant routing,\nand durable result handling still apply. The update capability is a governed\nmutation; the get capability is a governed read.\n\nHandle an operator workflow separately\n\nIf a deployment legitimately needs an excluded provider function, keep it\noutside the business connector and define a separate operator-owned workflow\nwith its own:\n• authenticated human or administrative service identity;\n• least-privilege provider credential and explicit secret custody;\n• browser state and callback validation where a session is involved;\n• ownership-proof handling and restricted audit evidence;\n• change approval, rotation, incident, and revocation procedure;\n• provider-specific versioning, validation, and recovery behavior.\n\nThis page does not define such an operator API or authorize a particular direct\nprovider call. The provider's current administrative documentation and the\ndeployment's security policy own that separate workflow.\n\nReview a proposed connector expansion\n\nMoving a route into the business surface is a protocol-facing security change,\nnot an inventory edit. Review all of the following together:\n1. explain the user outcome and why it belongs outside the operator plane;\n2. pin the exact upstream revision, method, version, and canonical path;\n3. define one bounded capability id and closed input and output schemas;\n4. partition path, query, and body fields without arbitrary pass-through;\n5. classify data, PII, side effects, risk, and credential scope;\n6. define approval, idempotency, transaction, compensation, and reconciliation;\n7. keep provider credentials, verification codes, and raw secrets out of input;\n8. add positive, negative, boundary, restart, and provider-contract tests;\n9. remove the exact pair from the exclusion inventory and preserve uniqueness\n   and disjointness checks;\n10. regenerate capability metadata, update public documentation, and qualify the\n    exact artifact before making a live claim.\n\nDo not add a generic method-plus-path capability. That would erase the fixed\nschema, policy, credential, and audit boundary established by the connector.\n\nAudit the exclusion boundary\n\n| Check | Expected result at this revision |\n\n| Published capability ids | 81 unique ids |\n| Operator-only inventory | 38 unique method-path pairs |\n| Deprecated alias inventory | 2 unique method-path pairs |\n| Combined excluded inventory | 40 unique pairs |\n| Published versus excluded pairs | Disjoint |\n| Manifest compatibility metadata | operatoronlyroutesexcluded: 38; deprecatedaliasesexcluded: 2 |\n| Unknown capability invocation | Rejected before provider dispatch |\n| Arbitrary provider proxy | Absent |\n\nThese checks establish an implementation boundary. They do not show that a\ncurrent provider deployment exposes, removes, or preserves any excluded route.\n\nSecurity and evidence boundaries\n• Provider-route discovery is not permission to invoke the route.\n• A provider GET verb is not evidence that a control-plane action is read-only.\n• Connector credentials must not be reused as a general provider admin token.\n• An excluded route has no inherited AIP approval or idempotency guarantee.\n• A deprecated alias has no compatibility promise from this connector.\n• Source tests prove inventory separation, not live provider behavior.\n\nRelated documentation\n• API versions and public provider routes (api-versions-and-provider-routes.md)\n• Cal.diy capability index (../capabilities/README.md)\n• Pinned upstream baselines (../../upstream-baselines.md)\n• Connector contract (../../../spec/connector-contract.md)\n• Build a connector (../../../guides/build-a-connector.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "fbfb631f7110980c3a63ba554f043844e493d0c0145ddc5f8289a07424d11ed5"
  }
}