---
id: CAP-PFM-INT-003
title: Adopt an integration with reviewed access
feature: FEAT-PFM-INT-01
product_area: platform
module: integrations
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
supersedes:
  - CAP-INT-CAT-007
  - CAP-INT-CAT-017
  - CAP-INT-LIB-005
  - CAP-INT-LIB-006
  - CAP-INT-LIB-007
  - CAP-INT-SEC-011
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
intent_sources:
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D4'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D7'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D11'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S03'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S04'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S13'
  - 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S17'
purpose: Administrators establish the workspace’s use of an integration with explicitly reviewed access and settings.
outcomes:
  - The saved installation reflects the administrator’s choices within the declared access.
  - 'Installation suspension blocks use, and removal ends its subscriptions.'
concepts:
  - CON-PFM-INT-001
actors:
  - ACT-PFM-017
  - ACT-PFM-018
  - ACT-PFM-006
surfaces:
  - console
  - api
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-003-01
    proved_by: [ATS-PFM-INT-002-06, ATS-PFM-INT-003-01, ATS-PFM-INT-003-12, TST-PFM-INT-505, TST-PFM-INT-551]
    statement: >-
      Installation requires an integration offered to the workspace and allows one installation per
      integration; attempts to install an existing enabled or suspended installation are refused without a
      second record.
    kind: validation
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#refuses
      an integration installed already, and writes no second
    origin: none
  - id: BR-CAP-PFM-INT-003-02
    proved_by: [ATS-PFM-INT-003-02, TST-PFM-INT-347, TST-PFM-INT-550, TST-PFM-INT-551, TST-PFM-INT-581]
    statement: >-
      Accepted capabilities, events, data fields and Rhythm permissions must fit the current integration
      declaration at installation and on edit; previously withdrawn declared access can be accepted again.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/installations/installation-lifecycle.ts:requireAcceptance
    origin: none
  - id: BR-CAP-PFM-INT-003-03
    proved_by: [ATS-PFM-INT-003-03, TST-PFM-INT-350, TST-PFM-INT-551, TST-PFM-INT-581]
    statement: >-
      Installation settings are validated against the provider’s declared form on creation and change, with
      each problem identified and no invalid value saved.
    kind: validation
    enforced_at:
      - service
      - console
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#refuses
      settings the manifest’s schema refuses, and writes nothing
    origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S04'
  - id: BR-CAP-PFM-INT-003-04
    proved_by: [ATS-PFM-INT-003-04, ATS-PFM-INT-003-12, TST-PFM-INT-551]
    statement: >-
      An installation edit must use the version read; a stale edit leaves the newer settings and acceptance
      untouched.
    kind: validation
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#refuses
      a stale version and leaves the settings as they were
    origin: none
  - id: BR-CAP-PFM-INT-003-05
    proved_by: [ATS-PFM-INT-003-05, TST-PFM-INT-531, TST-PFM-INT-539]
    statement: >-
      Withdrawing a capability blocks the next bound call before provider contact, and credential leases omit
      permissions the installation no longer accepts.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/executions/consent-narrowing.integration.spec.js#INT-ACC-0509
      step 4: refuses the refund 409 binding_ineligible
    origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D4'
  - id: BR-CAP-PFM-INT-003-06
    proved_by: [ATS-PFM-INT-003-06, ATS-PFM-INT-003-12, ATS-PFM-INT-003-13, TST-PFM-INT-551]
    statement: >-
      Suspension requires a reason, pauses active and degraded connections, and resume restores only
      connections paused by that installation; repeated state changes are refused.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#suspends
      the active and degraded connections of the installation when it is suspended
    origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S13'
  - id: BR-CAP-PFM-INT-003-07
    proved_by: [ATS-PFM-INT-003-07, ATS-PFM-INT-003-12, TST-PFM-INT-151, TST-PFM-INT-487, TST-PFM-INT-522]
    statement: >-
      An enabled or suspended installation can be uninstalled only after all its connections are disconnected;
      refusal identifies the remaining connections and successful removal preserves the installation record.
    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#is
      refused while a connection is not disconnected, naming each by id, name and status
    origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D11'
  - id: BR-CAP-PFM-INT-003-08
    proved_by: [ATS-PFM-INT-003-08, ATS-PFM-INT-003-14, ATS-PFM-INT-014-08, ATS-PFM-INT-014-12, TST-PFM-INT-522]
    statement: Uninstalling deletes the installation’s subscriptions and prevents new deliveries for them.
    kind: policy
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/connections/disconnect-discard-uninstall.integration.spec.js#removes
      every subscription of the installation with the uninstallation, and no other installation’s
    origin: none
  - id: BR-CAP-PFM-INT-003-09
    proved_by: [ATS-PFM-INT-003-12]
    statement: >-
      Reinstallation reuses the uninstalled record, enables it with the new acceptance and records a
      reinstallation event.
    kind: lifecycle
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/installations/installation-lifecycle.integration.spec.js#installs
      again as the same row, enabled with the new acceptance, audited as a reinstallation
    origin: none
  - id: BR-CAP-PFM-INT-003-10
    proved_by: [ATS-PFM-INT-003-09, ATS-PFM-INT-003-15, TST-PFM-INT-550]
    statement: >-
      Accepted installation changes enter integration history and the security trail, including whether access
      widens; refused changes enter neither trail.
    kind: invariant
    enforced_at:
      - service
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/installations/history-and-security-trail.integration.spec.js#writes
      the narrowing to the history and to the security trail
    origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.md#D4'
  - id: BR-CAP-PFM-INT-003-11
    proved_by: [ATS-PFM-INT-003-10, ATS-PFM-INT-003-16, ATS-PFM-INT-022-07, TST-PFM-INT-553]
    statement: >-
      Workspace deletion purges that workspace’s integration records and removes protected history last,
      without touching another workspace’s records.
    kind: lifecycle
    enforced_at:
      - service
      - database
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/integration/services/maintenance/tenant-participant.integration.spec.js#leaves
      every table of the module empty of the tenant, the ones the application can delete included
    origin: none
  - id: BR-CAP-PFM-INT-003-12
    proved_by: [ATS-PFM-INT-003-11, TST-PFM-INT-491, TST-PFM-INT-505]
    statement: >-
      A different workspace’s administrator is refused installation and connection reads and writes, including
      requests using known record identifiers.
    kind: permission
    enforced_at:
      - api
      - database
    must_prove: true
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/e2e/reader-access.e2e.spec.js#is refused every tenant route
      of this tenant, by id as by list (403)
    origin: 'services-platform:docs/milestones/INTG-M1-find-install-connect.plan.md#INTG-M1-S16'
scenarios:
  - id: SC-CAP-PFM-INT-003-01
    given: A provider requests several payment capabilities.
    when: 'The administrator installs it with a reduced selection, then submits access outside the declaration.'
    then: The reduced selection is retained and undeclared access is refused.
    provenance: test
    source: 'react-console:acceptance/integrations/playwright/journeys/library/INT-ACC-0006.spec.ts#INT-ACC-0006'
  - id: SC-CAP-PFM-INT-003-02
    given: Staff want to stop trusting an installed provider.
    when: 'They suspend it, disconnect its accounts and uninstall from suspended.'
    then: Use pauses and removal succeeds after the connection prerequisites are satisfied.
    provenance: test
    source: >-
      services-platform:modules/integrations/tests/e2e/disconnect-and-uninstall.e2e.spec.js#answers the
      uninstallation of a suspended installation 200 once every connection is disconnected
edge_cases: []
constraints: []
depends_on:
  - CAP-PFM-INT-002
related:
  - CAP-PFM-INT-004
  - CAP-PFM-INT-014
  - CAP-PFM-INT-006
journeys:
  - JNY-PFM-INT-001
  - JNY-PFM-INT-002
open_questions: []
evidence:
  - >-
    services-platform source inventory: modules/integrations/services/installations/installation-lifecycle.ts,
    settings-schema.ts, services/maintenance/tenant-participant.ts, services/state-refusals.ts; rule-level
    automated test references; docs/milestones/INTG-M1-find-install-connect.md (D4, D7, D11) and
    INTG-M1-decisions-2.md.
  - >-
    react-console source inventory: components/integrations/installation-detail.tsx, permission-checklist.tsx,
    lib/integrations/permissions.ts, schema-form.ts; acceptance journeys INT-ACC-0006, 0009, 0124.
  - >-
    Operation coverage: createIntegrationInstallation, listIntegrationInstallations,
    getIntegrationInstallation, updateIntegrationInstallation, suspendIntegrationInstallation,
    resumeIntegrationInstallation, uninstallIntegrationInstallation.
  - 'Persistent record coverage: integration_installations, integration_audit_events.'
  - 'End-to-end definition inventory: disconnect-and-uninstall.e2e.spec.js, reader-access.e2e.spec.js.'
controls: [TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-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-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, 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-01-01, FAS-PFM-INT-01-02, FAS-PFM-INT-01-03, FAS-PFM-INT-01-04, FAS-PFM-INT-01-05]
suites: [TST-PFM-INT-151, TST-PFM-INT-347, TST-PFM-INT-350, TST-PFM-INT-487, TST-PFM-INT-491, TST-PFM-INT-505, TST-PFM-INT-522, TST-PFM-INT-531, TST-PFM-INT-539, TST-PFM-INT-550, TST-PFM-INT-551, TST-PFM-INT-553, TST-PFM-INT-581]
---
# Adopt an integration with reviewed access

## Purpose

Administrators establish the workspace’s use of an integration with explicitly reviewed access and settings.

## How It Works

An administrator reviews the provider’s requested access and supplies its installation settings. Rhythm saves a workspace installation for subsequent account connections. Staff can revisit those choices and see when a newer edit makes their open copy stale. Suspension provides a pause for the whole installation. Resume distinguishes that pause from a connection suspended separately. Uninstallation requires the administrator to deal with remaining connections first. The retained record explains the earlier adoption even after use ends. Access restoration within a declaration is implemented, although the recorded narrow-only decision leaves its intended boundary unresolved. The product should settle that boundary before treating the observed edit behaviour as approved.

## Relationships

- Requires explore the integrations available to a workspace to supply the prerequisite configuration or operation.
- Connects with maintain a verified provider account connection through shared integration records.
- Connects with deliver subscribed rhythm changes to integrations through shared integration records.
- Connects with recognize integration problems and trace changes through shared integration records.