{
  "schemaVersion": "1.0",
  "title": "Rotate connector credentials",
  "description": "Use this guide to replace one provider credential used by a standalone connector host. The procedure creates a new tenant-owned connector instance, starts replicas with the new material, changes new route assignments to the new credential r",
  "canonical": "https://getaip.org/docs/guides/connector-credentials-and-rotation",
  "route": "/docs/guides/connector-credentials-and-rotation",
  "source": "docs/guides/connector-credentials-and-rotation.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Deploy and Operate",
  "documentType": "Guide",
  "language": "en",
  "downloads": {
    "md": "/docs/download/guides/connector-credentials-and-rotation.md",
    "txt": "/docs/download/guides/connector-credentials-and-rotation.txt",
    "json": "/docs/download/guides/connector-credentials-and-rotation.json",
    "pdf": "/docs/download/guides/connector-credentials-and-rotation.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Rotate connector credentials\ndescription: Replace one provider credential without exposing secrets or breaking pinned connector actions\nkind: how-to\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Rotate connector credentials\n\nUse this guide to replace one provider credential used by a standalone\nconnector host. The procedure creates a new tenant-owned connector instance,\nstarts replicas with the new material, changes new route assignments to the new\ncredential revision, and preserves already assigned actions on the old\nreplicas until they settle.\n\nThis is the safe default for Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and\nTwenty at source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`. Their host binaries read provider\nAPI, OAuth, sidecar, or webhook secrets during process startup. The common\ncredential revision policy reloads dynamically, but it does not reload or\nselect that product-owned secret material.\n\nUse the emergency procedure when the old credential may be compromised. It\nstops new work and fails old revisions closed before availability or graceful\ncompletion.\n\n## Understand the three credential layers\n\nDo not begin a rotation until the change record distinguishes these objects:\n\n| Layer | Stored where | Purpose | Contains secret material |\n|---|---|---|---|\n| Provider material | Product-owned secret files or external secret provider | Authenticates the connector to the external product | Yes |\n| Opaque credential handle | Host configuration | Names an issuer, handle, tenant, and verified scopes | No |\n| Credential revision reference | Tenant binding, durable route assignment, and host policy | Fences which credential generation may perform a provider side effect | No |\n\nThe registry copies a binding's `credential_revision_ref` into each new durable\nroute assignment. Resolving the same action ID again returns the existing\nassignment, including its original credential revision and exact replica. A\nlater binding update affects new actions only.\n\nImmediately before a provider side effect, the connector host checks the\nrevision from the signed route against its current policy. An authorized\nrevision permits execution. Authorization does not fetch a secret, replace a\nfile, or prove that the mounted material matches the label.\n\n## Choose the supported rotation shape\n\nUse a blue/green instance rotation for the six public hosts:\n\n```text\nold binding -> old instance -> old replicas -> old provider material\nnew binding -> new instance -> new replicas -> new provider material\n```\n\nKeep the new binding disabled while the new replicas register and become ready.\nAt cutover, stop admission of new actions, disable the old binding, enable the\nnew binding, verify the catalog, and resume admission. Existing action IDs stay\npinned to old replicas; fresh action IDs receive the new revision.\n\nDo not place old-secret and new-secret replicas under one instance during this\nrotation. The registry can send any new assignment for that instance to any\nready replica. Because the six current hosts load one product credential set at\nstartup, a mixed instance could label work with one revision while a replica\nuses material from the other.\n\nA same-instance rolling rotation is suitable only for a separately reviewed\nconnector whose credential provider resolves material by the pinned revision\nand can serve both revisions concurrently. The six current public host\nentrypoints do not establish that behavior.\n\n## Prerequisites\n\nBefore a routine rotation, require:\n\n- the exact active connector type and immutable version;\n- the old instance, replica, binding, policy, and credential revision IDs;\n- a new opaque revision ID containing 1–256 bytes;\n- a new provider credential created through the provider's approved process;\n- owner-controlled secret files or an external secret-provider revision;\n- new instance and replica IDs with reviewed endpoints and signing identities;\n- a complete signed admission package stream and its trust policy;\n- short-lived connector-registry administrator access;\n- a way to pause new action admission for the affected tenant and capability;\n- a non-mutating provider check and expected result;\n- visibility into active assignments, host readiness, errors, and provider\n  audit records;\n- a rollback window during which the old credential and old replicas remain\n  available.\n\nUse a distinct revision name that cannot be confused with a file version,\ndeployment timestamp, or mutable secret alias. Record a cryptographic or\nprovider-owned secret version identifier in the private change record, but do\nnot place it in public logs if it reveals provider internals.\n\n## Record the current boundary\n\nCapture a secret-free baseline before changing the provider or registry:\n\n| Item | Required value |\n|---|---|\n| Tenant and capability | Exact binding key |\n| Old instance | Tenant owner, external account, immutable connector version, and status |\n| Old binding | Priority, policy revision, credential revision, quota policy, and enabled state |\n| Old replicas | Endpoint, peer DID, trust domain, topology, status, lease, and active assignments |\n| Old host policy | Current, accepted previous, and revoked revision sets |\n| Product boundary | Account or workspace and required scopes, without secret bytes |\n| Evidence | Last known safe read, provider audit marker, and observation time |\n\nStop if the binding revision, instance owner, external account, or host policy\ndoes not match the approved record. First reconcile the unknown change; do not\nhide it inside a credential rotation.\n\n## Create and protect the new provider material\n\nCreate the replacement in the external provider with the smallest scopes\nrequired by the admitted capabilities. Keep the old credential active. Store\nthe new material through the product-specific mechanism documented for that\nconnector.\n\nFor the current six host binaries, secret inputs are regular non-symlink files\nwith no group or world permission bits on Unix. Mount a new immutable secret\nversion rather than overwriting the path used by a running old replica. Do not\nprint, hash into a public log, pass on a command line, or include the material\nin an admission package.\n\nAPI credentials and inbound webhook verification secrets are separate trust\nboundaries. Rotate only the intended boundary. If both must change, use the\nconnector-local runbook to preserve any provider-supported webhook overlap and\nrecord two independent verification results.\n\n## Prepare the new host policy\n\nConfigure each new replica with the complete common credential tuple:\n\n```text\ncredential id       = opaque handle for the new material\ncredential issuer   = approved internal issuer\ncredential scopes   = exact verified provider scopes\ncredential revision = credential-revision-new\ntenant              = the new instance tenant\n```\n\nSet `--credential-revision-policy-file` to a non-secret JSON file that\nauthorizes the new revision:\n\n```json\n{\n  \"current_revision_ref\": \"credential-revision-new\",\n  \"accepted_previous_revisions\": [],\n  \"revoked_revisions\": []\n}\n```\n\nThe file rejects unknown fields and overlapping sets. Replace it atomically on\nthe same filesystem; a partial, unreadable, or invalid document makes provider\nwork unavailable. The common host validates at startup that this policy\nauthorizes the configured revision and reloads it before every provider side\neffect.\n\nDo not add the old revision to a new replica's policy merely to make a health\ncheck pass. A new replica that lacks the old provider material must not claim it\ncan execute old-revision work.\n\n## Admit the green instance with traffic disabled\n\nCreate the next monotonic admission package revision. It remains a complete,\nsigned package with the immutable connector version and required evidence; it\nis not a secret-rotation patch format. Include:\n\n- the new tenant-owned instance with the same intended external account\n  boundary;\n- new pre-provisioned replicas in `offline` state with zero active assignments;\n- one binding per affected capability for the new instance;\n- a higher binding `policy_revision` than any existing record for the same\n  tenant, capability, and instance key;\n- `credential_revision_ref` set to the new opaque revision;\n- `enabled` set to `false`;\n- the reviewed priority and quota policy.\n\nPlan the signed package without writing:\n\n```sh\naipctl connector registry plan \\\n  --package rotation-stage-signed.json \\\n  --trust-policy admission-trust-policy.json\n```\n\nCompare the returned package ID, revision, digest, instance count, replica\ncount, and binding count with the approved change. Apply only those exact\nbytes:\n\n```sh\naipctl connector registry apply \\\n  --package rotation-stage-signed.json \\\n  --trust-policy admission-trust-policy.json \\\n  --database-url-file /run/operator/registry-admin.url\n```\n\nThen read the durable operation record:\n\n```sh\naipctl connector registry status \\\n  --package-id \"$PACKAGE_ID\" \\\n  --revision \"$PACKAGE_REVISION\" \\\n  --database-url-file /run/operator/registry-admin.url\n```\n\nRequire an applied state. Close and unmount administrator access after the\nshort-lived operation. The disabled binding must not appear in tenant-visible\ncapability discovery.\n\n## Start and verify the green replicas\n\nStart the new hosts with their new instance, replica, configuration revision,\ncredential handle, credential revision, policy file, and provider secret paths.\nDo not reuse an old replica ID or signing seed.\n\nFor every new replica, verify:\n\n1. `/health` identifies an AIP 1.0 connector host;\n2. `/ready` reports a valid lease, no drain, durable storage ready, and product\n   connector ready;\n3. registry state matches the admitted endpoint, peer DID, trust domain,\n   artifact digest, topology, and configuration revision;\n4. the deployment secret mount contains the intended private version without\n   exposing its bytes;\n5. the provider's approved non-mutating credential check succeeds;\n6. a deliberately invalid or under-scoped credential check fails as expected;\n7. no production tenant binding routes new work to the green instance yet.\n\nHost readiness is necessary but insufficient. A product health implementation\nmay not exercise every scope or operation. Retain the provider audit record and\nthe connector-local check result as separate evidence.\n\n## Prepare the cutover package\n\nCreate another signed admission package revision containing both binding\ntransitions for every affected capability:\n\n| Binding | Instance | Credential revision | Enabled | Policy revision |\n|---|---|---|---|---|\n| Old | Old instance | Old revision | `false` | Greater than its current value |\n| New | New instance | New revision | `true` | Greater than its staged value |\n\nInclude both referenced instances in the package. Keep the same exact tenant,\ncapability IDs, quota intent, and reviewed priority semantics. A missing old\nbinding does not delete or disable it; the package must explicitly write its\nnew disabled state.\n\nRun `aipctl connector registry plan` and compare the signed digest with the\nchange record. Do not use `connector registry revoke` for routine rotation:\nthat command revokes the entire connector version represented by an applied\npackage, not one credential.\n\n## Cut over new assignments\n\nAdmission package catalog writes are individually durable and idempotent, but\nthe complete binding list is not committed as one database transaction.\nTherefore perform the binding transition inside a bounded admission pause:\n\n1. stop acceptance of new actions for the affected tenant and capabilities;\n2. allow already accepted requests to obtain or reuse their durable\n   assignments;\n3. apply the exact cutover package with short-lived administrator access;\n4. require the package operation to report `applied`;\n5. query tenant-scoped capability discovery and confirm that only the green\n   enabled binding is eligible;\n6. submit one new non-mutating action with a fresh action ID;\n7. confirm its durable assignment names the green instance, a green replica,\n   and the new credential revision;\n8. confirm the external provider observed the intended account and scope;\n9. resume new action admission.\n\nStop and keep admission paused if discovery is empty, both instances remain\neligible, the route carries the wrong revision, or the provider result cannot\nbe attributed safely. Do not test cutover with a mutation.\n\n## Preserve and retire the old path\n\nKeep the old replicas, host policy, and provider credential available while\nold durable assignments can still resume. Disabling the old binding prevents\nnew assignments; it does not rewrite or delete an existing action's pinned\nroute.\n\nTrack old assignments until every item is terminal or explicitly reconciled.\nInclude queued, running, awaiting-approval, retryable, delegated, and streaming\nwork in that inventory. A low current in-flight gauge alone does not prove that\nno durable retry can return.\n\nAfter the retention boundary is satisfied:\n\n1. drain each old replica through the signed lifecycle service;\n2. verify it accepts no new work and reaches `offline`;\n3. preserve the secret-free assignment and provider audit records;\n4. revoke or delete the old provider credential through the provider's\n   approved control plane;\n5. remove the old secret mount and backups according to retention policy;\n6. retain the old binding as disabled audit state unless a separate registry\n   lifecycle procedure owns deletion;\n7. close the rotation record with the new binding, route, provider, and\n   retirement evidence.\n\n## Roll back a routine rotation\n\nRollback is safe only while the old credential and old replicas remain usable.\nPause new admission again and apply a new package revision that disables the\ngreen binding and re-enables the old binding with higher policy revisions. Do\nnot reuse a previously applied package revision or edit its signed bytes.\n\nVerify that a fresh non-mutating action pins the old instance and old credential\nrevision before resuming admission. Actions already assigned to the green\ninstance remain pinned there. Keep green replicas available until those actions\nsettle, or classify each unresolved provider effect before containment.\n\nA binding rollback does not undo an external provider mutation. Use action\nidempotency, receipts, provider audit data, and the connector-local recovery\nprocedure to decide whether an uncertain action completed. Never retry an\nambiguous mutation with a new action ID merely because routing changed.\n\n## Revoke a suspected compromised credential\n\nWhen confidentiality or integrity may be lost, prioritize containment:\n\n1. pause affected new action admission;\n2. atomically replace the revision policy on every reachable old host so the\n   old revision appears only in `revoked_revisions`;\n3. apply a signed package revision that disables every binding carrying the old\n   revision;\n4. revoke the provider credential through the provider control plane;\n5. drain or isolate old replicas;\n6. inventory actions that may already have passed the pre-side-effect revision\n   check;\n7. reconcile their provider outcomes before retry or compensation;\n8. deploy and enable a green instance only after new material and scopes are\n   verified.\n\nA revoked revision returns HTTP 403 with\n`connector_host.credential_revision_denied`; it is non-retryable. An unreadable\nor invalid policy returns HTTP 503 with\n`connector_host.credential_revision_unavailable`; it is temporary and suggests\na 1,000 ms retry. During a compromise, do not treat an unavailable policy as\npermission to bypass the check.\n\nThe policy check occurs immediately before the host passes the action into the\ngateway. Work already beyond that boundary may have reached the provider.\nRecord those actions as potentially ambiguous until provider evidence resolves\nthem.\n\nUse package-wide revocation only when the entire admitted connector version\nmust stop. It changes the version status to `revoked` and affects unrelated\ninstances using that exact version.\n\n## Completion criteria\n\nClose the rotation only when all of the following are true:\n\n- fresh actions pin the green instance, replica, and credential revision;\n- the provider confirms the expected account and least-privilege scopes;\n- tenant discovery exposes no enabled old binding;\n- old assignments are terminal or individually reconciled;\n- old replicas are offline;\n- the old provider credential is revoked;\n- no secret value appears in packages, logs, metrics, receipts, or retained\n  screenshots;\n- rollback or emergency decisions and their evidence are retained;\n- qualification and production-readiness claims remain limited to their actual\n  evidence.\n\nFor exact common fields and policy-file constraints, see\n[Connector host configuration](../reference/connector-host-configuration.md).\nUse [Deploy the connector fleet](deploy-connector-fleet.md) for admission and\nhost startup, [Identity and trust](../concepts/identity-and-trust.md) for the\ncredential boundary, [Deploy AIP in production](production-deployment.md) for\noperational ownership, and [Connector catalog](../connectors/README.md) for the\nsix product-specific configuration and recovery paths.\n",
    "text": "Rotate connector credentials\n\nUse this guide to replace one provider credential used by a standalone\nconnector host. The procedure creates a new tenant-owned connector instance,\nstarts replicas with the new material, changes new route assignments to the new\ncredential revision, and preserves already assigned actions on the old\nreplicas until they settle.\n\nThis is the safe default for Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and\nTwenty at source revision\n97be86e9efedf07ecf1783b03800f683f107fb04. Their host binaries read provider\nAPI, OAuth, sidecar, or webhook secrets during process startup. The common\ncredential revision policy reloads dynamically, but it does not reload or\nselect that product-owned secret material.\n\nUse the emergency procedure when the old credential may be compromised. It\nstops new work and fails old revisions closed before availability or graceful\ncompletion.\n\nUnderstand the three credential layers\n\nDo not begin a rotation until the change record distinguishes these objects:\n\n| Layer | Stored where | Purpose | Contains secret material |\n\n| Provider material | Product-owned secret files or external secret provider | Authenticates the connector to the external product | Yes |\n| Opaque credential handle | Host configuration | Names an issuer, handle, tenant, and verified scopes | No |\n| Credential revision reference | Tenant binding, durable route assignment, and host policy | Fences which credential generation may perform a provider side effect | No |\n\nThe registry copies a binding's credentialrevisionref into each new durable\nroute assignment. Resolving the same action ID again returns the existing\nassignment, including its original credential revision and exact replica. A\nlater binding update affects new actions only.\n\nImmediately before a provider side effect, the connector host checks the\nrevision from the signed route against its current policy. An authorized\nrevision permits execution. Authorization does not fetch a secret, replace a\nfile, or prove that the mounted material matches the label.\n\nChoose the supported rotation shape\n\nUse a blue/green instance rotation for the six public hosts:\n\nold binding -> old instance -> old replicas -> old provider material\nnew binding -> new instance -> new replicas -> new provider material\n\nKeep the new binding disabled while the new replicas register and become ready.\nAt cutover, stop admission of new actions, disable the old binding, enable the\nnew binding, verify the catalog, and resume admission. Existing action IDs stay\npinned to old replicas; fresh action IDs receive the new revision.\n\nDo not place old-secret and new-secret replicas under one instance during this\nrotation. The registry can send any new assignment for that instance to any\nready replica. Because the six current hosts load one product credential set at\nstartup, a mixed instance could label work with one revision while a replica\nuses material from the other.\n\nA same-instance rolling rotation is suitable only for a separately reviewed\nconnector whose credential provider resolves material by the pinned revision\nand can serve both revisions concurrently. The six current public host\nentrypoints do not establish that behavior.\n\nPrerequisites\n\nBefore a routine rotation, require:\n• the exact active connector type and immutable version;\n• the old instance, replica, binding, policy, and credential revision IDs;\n• a new opaque revision ID containing 1–256 bytes;\n• a new provider credential created through the provider's approved process;\n• owner-controlled secret files or an external secret-provider revision;\n• new instance and replica IDs with reviewed endpoints and signing identities;\n• a complete signed admission package stream and its trust policy;\n• short-lived connector-registry administrator access;\n• a way to pause new action admission for the affected tenant and capability;\n• a non-mutating provider check and expected result;\n• visibility into active assignments, host readiness, errors, and provider\n  audit records;\n• a rollback window during which the old credential and old replicas remain\n  available.\n\nUse a distinct revision name that cannot be confused with a file version,\ndeployment timestamp, or mutable secret alias. Record a cryptographic or\nprovider-owned secret version identifier in the private change record, but do\nnot place it in public logs if it reveals provider internals.\n\nRecord the current boundary\n\nCapture a secret-free baseline before changing the provider or registry:\n\n| Item | Required value |\n\n| Tenant and capability | Exact binding key |\n| Old instance | Tenant owner, external account, immutable connector version, and status |\n| Old binding | Priority, policy revision, credential revision, quota policy, and enabled state |\n| Old replicas | Endpoint, peer DID, trust domain, topology, status, lease, and active assignments |\n| Old host policy | Current, accepted previous, and revoked revision sets |\n| Product boundary | Account or workspace and required scopes, without secret bytes |\n| Evidence | Last known safe read, provider audit marker, and observation time |\n\nStop if the binding revision, instance owner, external account, or host policy\ndoes not match the approved record. First reconcile the unknown change; do not\nhide it inside a credential rotation.\n\nCreate and protect the new provider material\n\nCreate the replacement in the external provider with the smallest scopes\nrequired by the admitted capabilities. Keep the old credential active. Store\nthe new material through the product-specific mechanism documented for that\nconnector.\n\nFor the current six host binaries, secret inputs are regular non-symlink files\nwith no group or world permission bits on Unix. Mount a new immutable secret\nversion rather than overwriting the path used by a running old replica. Do not\nprint, hash into a public log, pass on a command line, or include the material\nin an admission package.\n\nAPI credentials and inbound webhook verification secrets are separate trust\nboundaries. Rotate only the intended boundary. If both must change, use the\nconnector-local runbook to preserve any provider-supported webhook overlap and\nrecord two independent verification results.\n\nPrepare the new host policy\n\nConfigure each new replica with the complete common credential tuple:\n\ncredential id       = opaque handle for the new material\ncredential issuer   = approved internal issuer\ncredential scopes   = exact verified provider scopes\ncredential revision = credential-revision-new\ntenant              = the new instance tenant\n\nSet --credential-revision-policy-file to a non-secret JSON file that\nauthorizes the new revision:\n\n{\n  \"currentrevisionref\": \"credential-revision-new\",\n  \"acceptedpreviousrevisions\": [],\n  \"revokedrevisions\": []\n}\n\nThe file rejects unknown fields and overlapping sets. Replace it atomically on\nthe same filesystem; a partial, unreadable, or invalid document makes provider\nwork unavailable. The common host validates at startup that this policy\nauthorizes the configured revision and reloads it before every provider side\neffect.\n\nDo not add the old revision to a new replica's policy merely to make a health\ncheck pass. A new replica that lacks the old provider material must not claim it\ncan execute old-revision work.\n\nAdmit the green instance with traffic disabled\n\nCreate the next monotonic admission package revision. It remains a complete,\nsigned package with the immutable connector version and required evidence; it\nis not a secret-rotation patch format. Include:\n• the new tenant-owned instance with the same intended external account\n  boundary;\n• new pre-provisioned replicas in offline state with zero active assignments;\n• one binding per affected capability for the new instance;\n• a higher binding policyrevision than any existing record for the same\n  tenant, capability, and instance key;\n• credentialrevisionref set to the new opaque revision;\n• enabled set to false;\n• the reviewed priority and quota policy.\n\nPlan the signed package without writing:\n\naipctl connector registry plan \\\n  --package rotation-stage-signed.json \\\n  --trust-policy admission-trust-policy.json\n\nCompare the returned package ID, revision, digest, instance count, replica\ncount, and binding count with the approved change. Apply only those exact\nbytes:\n\naipctl connector registry apply \\\n  --package rotation-stage-signed.json \\\n  --trust-policy admission-trust-policy.json \\\n  --database-url-file /run/operator/registry-admin.url\n\nThen read the durable operation record:\n\naipctl connector registry status \\\n  --package-id \"$PACKAGEID\" \\\n  --revision \"$PACKAGEREVISION\" \\\n  --database-url-file /run/operator/registry-admin.url\n\nRequire an applied state. Close and unmount administrator access after the\nshort-lived operation. The disabled binding must not appear in tenant-visible\ncapability discovery.\n\nStart and verify the green replicas\n\nStart the new hosts with their new instance, replica, configuration revision,\ncredential handle, credential revision, policy file, and provider secret paths.\nDo not reuse an old replica ID or signing seed.\n\nFor every new replica, verify:\n1. /health identifies an AIP 1.0 connector host;\n2. /ready reports a valid lease, no drain, durable storage ready, and product\n   connector ready;\n3. registry state matches the admitted endpoint, peer DID, trust domain,\n   artifact digest, topology, and configuration revision;\n4. the deployment secret mount contains the intended private version without\n   exposing its bytes;\n5. the provider's approved non-mutating credential check succeeds;\n6. a deliberately invalid or under-scoped credential check fails as expected;\n7. no production tenant binding routes new work to the green instance yet.\n\nHost readiness is necessary but insufficient. A product health implementation\nmay not exercise every scope or operation. Retain the provider audit record and\nthe connector-local check result as separate evidence.\n\nPrepare the cutover package\n\nCreate another signed admission package revision containing both binding\ntransitions for every affected capability:\n\n| Binding | Instance | Credential revision | Enabled | Policy revision |\n\n| Old | Old instance | Old revision | false | Greater than its current value |\n| New | New instance | New revision | true | Greater than its staged value |\n\nInclude both referenced instances in the package. Keep the same exact tenant,\ncapability IDs, quota intent, and reviewed priority semantics. A missing old\nbinding does not delete or disable it; the package must explicitly write its\nnew disabled state.\n\nRun aipctl connector registry plan and compare the signed digest with the\nchange record. Do not use connector registry revoke for routine rotation:\nthat command revokes the entire connector version represented by an applied\npackage, not one credential.\n\nCut over new assignments\n\nAdmission package catalog writes are individually durable and idempotent, but\nthe complete binding list is not committed as one database transaction.\nTherefore perform the binding transition inside a bounded admission pause:\n1. stop acceptance of new actions for the affected tenant and capabilities;\n2. allow already accepted requests to obtain or reuse their durable\n   assignments;\n3. apply the exact cutover package with short-lived administrator access;\n4. require the package operation to report applied;\n5. query tenant-scoped capability discovery and confirm that only the green\n   enabled binding is eligible;\n6. submit one new non-mutating action with a fresh action ID;\n7. confirm its durable assignment names the green instance, a green replica,\n   and the new credential revision;\n8. confirm the external provider observed the intended account and scope;\n9. resume new action admission.\n\nStop and keep admission paused if discovery is empty, both instances remain\neligible, the route carries the wrong revision, or the provider result cannot\nbe attributed safely. Do not test cutover with a mutation.\n\nPreserve and retire the old path\n\nKeep the old replicas, host policy, and provider credential available while\nold durable assignments can still resume. Disabling the old binding prevents\nnew assignments; it does not rewrite or delete an existing action's pinned\nroute.\n\nTrack old assignments until every item is terminal or explicitly reconciled.\nInclude queued, running, awaiting-approval, retryable, delegated, and streaming\nwork in that inventory. A low current in-flight gauge alone does not prove that\nno durable retry can return.\n\nAfter the retention boundary is satisfied:\n1. drain each old replica through the signed lifecycle service;\n2. verify it accepts no new work and reaches offline;\n3. preserve the secret-free assignment and provider audit records;\n4. revoke or delete the old provider credential through the provider's\n   approved control plane;\n5. remove the old secret mount and backups according to retention policy;\n6. retain the old binding as disabled audit state unless a separate registry\n   lifecycle procedure owns deletion;\n7. close the rotation record with the new binding, route, provider, and\n   retirement evidence.\n\nRoll back a routine rotation\n\nRollback is safe only while the old credential and old replicas remain usable.\nPause new admission again and apply a new package revision that disables the\ngreen binding and re-enables the old binding with higher policy revisions. Do\nnot reuse a previously applied package revision or edit its signed bytes.\n\nVerify that a fresh non-mutating action pins the old instance and old credential\nrevision before resuming admission. Actions already assigned to the green\ninstance remain pinned there. Keep green replicas available until those actions\nsettle, or classify each unresolved provider effect before containment.\n\nA binding rollback does not undo an external provider mutation. Use action\nidempotency, receipts, provider audit data, and the connector-local recovery\nprocedure to decide whether an uncertain action completed. Never retry an\nambiguous mutation with a new action ID merely because routing changed.\n\nRevoke a suspected compromised credential\n\nWhen confidentiality or integrity may be lost, prioritize containment:\n1. pause affected new action admission;\n2. atomically replace the revision policy on every reachable old host so the\n   old revision appears only in revokedrevisions;\n3. apply a signed package revision that disables every binding carrying the old\n   revision;\n4. revoke the provider credential through the provider control plane;\n5. drain or isolate old replicas;\n6. inventory actions that may already have passed the pre-side-effect revision\n   check;\n7. reconcile their provider outcomes before retry or compensation;\n8. deploy and enable a green instance only after new material and scopes are\n   verified.\n\nA revoked revision returns HTTP 403 with\nconnectorhost.credentialrevisiondenied; it is non-retryable. An unreadable\nor invalid policy returns HTTP 503 with\nconnectorhost.credentialrevisionunavailable; it is temporary and suggests\na 1,000 ms retry. During a compromise, do not treat an unavailable policy as\npermission to bypass the check.\n\nThe policy check occurs immediately before the host passes the action into the\ngateway. Work already beyond that boundary may have reached the provider.\nRecord those actions as potentially ambiguous until provider evidence resolves\nthem.\n\nUse package-wide revocation only when the entire admitted connector version\nmust stop. It changes the version status to revoked and affects unrelated\ninstances using that exact version.\n\nCompletion criteria\n\nClose the rotation only when all of the following are true:\n• fresh actions pin the green instance, replica, and credential revision;\n• the provider confirms the expected account and least-privilege scopes;\n• tenant discovery exposes no enabled old binding;\n• old assignments are terminal or individually reconciled;\n• old replicas are offline;\n• the old provider credential is revoked;\n• no secret value appears in packages, logs, metrics, receipts, or retained\n  screenshots;\n• rollback or emergency decisions and their evidence are retained;\n• qualification and production-readiness claims remain limited to their actual\n  evidence.\n\nFor exact common fields and policy-file constraints, see\nConnector host configuration (../reference/connector-host-configuration.md).\nUse Deploy the connector fleet (deploy-connector-fleet.md) for admission and\nhost startup, Identity and trust (../concepts/identity-and-trust.md) for the\ncredential boundary, Deploy AIP in production (production-deployment.md) for\noperational ownership, and Connector catalog (../connectors/README.md) for the\nsix product-specific configuration and recovery paths.\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "e6deae1b8eca05fbf64038584b2c37eda48588a09d3fb8e77561bccf3f4ad6d7"
  }
}