---
id: CAP-PFM-INT-004
title: Maintain a verified provider account connection
feature: FEAT-PFM-INT-02
product_area: platform
module: integrations
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes:
  - CAP-INT-CAT-008
  - CAP-INT-CAT-009
  - CAP-INT-CAT-010
  - CAP-INT-CAT-012
  - CAP-INT-LIB-008
  - CAP-INT-LIB-009
  - CAP-INT-LIB-010
  - CAP-INT-BND-009
  - CAP-INT-SEC-008
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D7'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D9'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D10'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S05'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S06'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S09'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S11'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S12'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S19'
purpose: Administrators maintain the provider account that an integration uses for the workspace.
outcomes:
  - Successful account verification establishes connection usability.
  - A binding prevents accidental removal of the connection it selects.
  - An abandoned initial connection can be discarded.
concepts:
  - CON-PFM-INT-002
actors:
  - ACT-PFM-017
  - ACT-PFM-018
  - ACT-PFM-006
surfaces:
  - console
  - api
  - job
preconditions: []
postconditions: []
permissions:
  - key: platform.integrations.manage
    where_checked: api
    scope: tenant
  - key: platform.integrations.read
    where_checked: api
    scope: tenant
  - key: platform.integrations.manage
    where_checked: console
    scope: tenant
rules:
  - id: BR-CAP-PFM-INT-004-01
    proved_by: [ATS-PFM-INT-004-01, TST-PFM-INT-489, TST-PFM-INT-520]
    statement: >-
      Creation requires an enabled installation and supported authentication, pins the current published
      release and waits for credentials; a platform-account connection instead begins verification with a job.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/e2e/integrations.e2e.spec.js#connects a platform account,
      which starts verifying with its job
    origin: none
  - id: BR-CAP-PFM-INT-004-02
    proved_by: [ATS-PFM-INT-004-02, TST-PFM-INT-489]
    statement: >-
      A connection uses its supplied identifier or one derived from its name, conforms to configuration
      identifier syntax and is unique within the workspace; conflicts identify the taken value.
    kind: validation
    enforced_at:
      - api
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/e2e/integrations.e2e.spec.js#refuses a second connection of
      the tenant whose name derives to a taken id, 409 naming the id
    origin: none
  - id: BR-CAP-PFM-INT-004-03
    proved_by: [ATS-PFM-INT-004-03, TST-PFM-INT-500, TST-PFM-INT-520]
    statement: >-
      An installation cannot hold two non-disconnected connections for the same provider account; verification
      of a duplicate ends in failed verification with its cause.
    kind: invariant
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/db/integration-connections.table.integration.spec.js#refuses
      the same provider account connected twice under the installation
    origin: none
  - id: BR-CAP-PFM-INT-004-04
    proved_by: [ATS-PFM-INT-004-04, ATS-PFM-INT-004-11, TST-PFM-INT-523, TST-PFM-INT-574]
    statement: >-
      Connection changes use permitted named transitions, leave disconnected final and write both audit trails
      and binding notifications; a refused transition makes no change.
    kind: invariant
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/unit/services/connection-state-machine.spec.ts#is chapter
      09 §4.3’s, edge for edge, and the three discards of INTG-M1 (D7)
    origin: none
  - id: BR-CAP-PFM-INT-004-05
    proved_by: [ATS-PFM-INT-004-05, ATS-PFM-INT-004-12, ATS-PFM-INT-004-14, ATS-PFM-INT-004-15, ATS-PFM-INT-005-16, ATS-PFM-INT-006-13, ATS-PFM-INT-013-12]
    statement: >-
      Passing verification records the account and supported features, activates the connection and provisions
      its declared webhook endpoints; failure records the provider’s reason and can be retried.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/connections/connection-jobs.integration.spec.js#becomes
      active with the account and every declared feature verified
    origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S05'
  - id: BR-CAP-PFM-INT-004-06
    proved_by: [ATS-PFM-INT-003-13, ATS-PFM-INT-004-06, TST-PFM-INT-404, TST-PFM-INT-550]
    statement: >-
      Only active or degraded connections can be suspended, suspension blocks their use, and suspension and
      resume record the actor and reason.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/installations/history-and-security-trail.integration.spec.js#refuses
      a suspension of a connection that is not active, recording it in neither trail
    origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S09'
  - id: BR-CAP-PFM-INT-004-07
    proved_by: [ATS-PFM-INT-004-07, ATS-PFM-INT-004-13, ATS-PFM-INT-007-14, TST-PFM-INT-368, TST-PFM-INT-487, TST-PFM-INT-513]
    statement: >-
      Disconnection accepts active, degraded, suspended, re-authorization-required or previously verified
      failed connections, but refuses while any current binding selects it, identifies the bindings and offers
      no override.
    kind: policy
    enforced_at:
      - api
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/e2e/disconnect-and-uninstall.e2e.spec.js#answers a
      disconnection of a bound connection 409, code connection_has_bindings, naming each binding
    origin: none
  - id: BR-CAP-PFM-INT-004-08
    proved_by: [ATS-PFM-INT-004-08, TST-PFM-INT-354, TST-PFM-INT-522]
    statement: >-
      An initial connection awaiting authentication, verifying for the first time or failed without prior
      success may be discarded into disconnected, with a discard reason, so it no longer prevents uninstall.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/connections/disconnect-discard-uninstall.integration.spec.js#ends
      a pending_auth connection disconnected, by the caller, with a reason saying it was discarded before it
      was ever connected
    origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D7'
  - id: BR-CAP-PFM-INT-004-09
    proved_by: [ATS-PFM-INT-004-09, ATS-PFM-INT-005-13, ATS-PFM-INT-013-09, TST-PFM-INT-523, TST-PFM-INT-538]
    statement: >-
      Disconnection disables webhook endpoints, revokes credentials for later secret deletion, clears
      connection notices and records the responsible person and reason.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/connections/transition.integration.spec.js#disables
      the connection’s webhook endpoints
    origin: none
  - id: BR-CAP-PFM-INT-004-10
    proved_by: [ATS-PFM-INT-001-15, ATS-PFM-INT-004-10, TST-PFM-INT-452, TST-PFM-INT-520, TST-PFM-INT-521]
    statement: >-
      Only active or degraded connections can move to a different published release of the same integration;
      newly requested access must already be covered by the old release or acceptance, and the pin changes
      after successful verification of the same account.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/connections/connection-operations.ts:requestVersionUpdate
    origin: none
  - id: BR-CAP-PFM-INT-004-11
    proved_by: []
    statement: >-
      Concurrent requests for the same open verification or health check reuse its job rather than create
      another.
    kind: invariant
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/connections/connection-job-dedup.integration.spec.js#answers
      one job to both requests, which the connection’s lock serializes
    origin: none
  - id: BR-CAP-PFM-INT-004-12
    proved_by: []
    statement: >-
      Connection discovery can filter for active connections with a verified capability feature, without
      exposing credentials.
    kind: policy
    enforced_at:
      - api
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/e2e/integrations.e2e.spec.js#discovers the connection once
      it is active with the feature verified, and answers no credential
    origin: none
scenarios:
  - id: SC-CAP-PFM-INT-004-01
    given: The browser closes during an initial connection attempt.
    when: The administrator returns to remove the installation.
    then: Discarding the unfinished connection permits the subsequent uninstall.
    provenance: test
    source: 'react-console:acceptance/integrations/playwright/journeys/library/INT-ACC-0013.spec.ts#INT-ACC-0013'
  - id: SC-CAP-PFM-INT-004-02
    given: Two business-unit bindings select Main account.
    when: The administrator requests disconnection.
    then: The refusal identifies both dependent bindings.
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/connections/disconnect-discard-uninstall.integration.spec.js#names
      each binding in the sentence a person reads
edge_cases: []
constraints: []
depends_on:
  - CAP-PFM-INT-003
  - CAP-PFM-INT-005
related:
  - CAP-PFM-INT-006
  - CAP-PFM-INT-007
journeys:
  - JNY-PFM-INT-001
  - JNY-PFM-INT-002
open_questions: []
evidence:
  - >-
    services-platform source inventory: modules/integrations/services/connections/transition.ts
    (CONNECTION_TRANSITIONS), connection-operations.ts, verify-connection.ts, submit-connection-jobs.ts,
    services/state-refusals.ts, db/integration-connections.table.ts;
    aws/logic/integrations-connection-verification.step-function.ts; rule-level automated test references;
    docs/integrations/README.md (The connection state machine); docs/milestones/INTG-M1-*.
  - >-
    react-console source inventory: components/integrations/connection-wizard.tsx, connection-detail.tsx,
    lib/integrations/lifecycle.ts; acceptance journeys INT-ACC-0013, 0016, 0027, 0063, 0130, 0535.
  - >-
    Operation coverage: createIntegrationConnection, listIntegrationConnections, getIntegrationConnection,
    updateIntegrationConnection, verifyIntegrationConnection, suspendIntegrationConnection,
    resumeIntegrationConnection, disconnectIntegrationConnection, updateIntegrationConnectionVersion.
  - >-
    Persistent record coverage: integration_connections, integration_verification_jobs,
    integration_verification_job_steps, integration_verification_job_events, integration_webhook_endpoints.
  - >-
    End-to-end definition inventory: integrations.e2e.spec.js, disconnect-and-uninstall.e2e.spec.js,
    reader-access.e2e.spec.js, verification-dummy.adapters.spec.js.
controls: [TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
exercised_by: [FAS-PFM-INT-02-01, FAS-PFM-INT-02-02, FAS-PFM-INT-02-03, FAS-PFM-INT-02-04, FAS-PFM-INT-02-05]
suites: [TST-PFM-INT-354, TST-PFM-INT-368, TST-PFM-INT-404, TST-PFM-INT-452, TST-PFM-INT-487, TST-PFM-INT-489, TST-PFM-INT-500, TST-PFM-INT-513, TST-PFM-INT-520, TST-PFM-INT-521, TST-PFM-INT-522, TST-PFM-INT-523, TST-PFM-INT-538, TST-PFM-INT-550, TST-PFM-INT-574]
---
# Maintain a verified provider account connection

## Purpose

Administrators maintain the provider account that an integration uses for the workspace.

## How It Works

An administrator names the provider account connection and chooses a supported authentication method. Rhythm checks the account before treating it as usable. The connection page provides the account’s standing and the means to request another check. A provider refusal gives staff a reason to correct credentials or investigate the account. Suspension pauses a usable connection without erasing it. Version changes use verification to protect the account identity. Disconnection requires dependent choices to be dealt with first. An abandoned initial attempt has a discard path so it does not trap the installation. The product should preserve these separate meanings when presenting pause, upgrade and removal.

## Relationships

- Requires adopt an integration with reviewed access to supply the prerequisite configuration or operation.
- Requires protect credentials throughout their useful life to supply the prerequisite configuration or operation.
- Connects with recognize integration problems and trace changes through shared integration records.
- Connects with assign provider connections to business needs through shared integration records.