--- id: CON-PFM-INT-002 name: Connection feature: FEAT-PFM-INT-02 product_area: platform module: integrations revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A connection is a workspace’s link to a provider account through an installed integration, carrying authentication facts, verified capabilities and observed health. owned_by: MOD-PFM-INT synonyms: - Account - Connected account not_to_be_confused_with: - Customer adoption and accepted access - Account routing selection facets: - name: Status meaning: 'Authentication, verification, usability, pause and final disconnection are distinct connection states.' used_for: Controlling when an account can receive work. - name: Version pin meaning: >- The pinned release supplies the connection’s provider implementation until a verified upgrade changes it. used_for: Maintaining predictable behaviour across releases. - name: Authentication method and credential meaning: >- The selected method associates the account with entered credentials, provider authorization or Rhythm’s platform account. used_for: Authenticating operations while exposing only safe credential facts. - name: Verified account and features meaning: 'Verification records account identity, supported features and a valid test or live environment report.' used_for: 'Checking bindings, discovering usable accounts and gating test calls.' - name: Health and figures meaning: Probe results and recent call statistics describe operational standing. used_for: Recognizing and investigating provider problems. - name: Webhook endpoints meaning: Provisioned public endpoints receive account notifications using signing secrets. used_for: Bringing provider changes back into Rhythm. - name: Connector notices meaning: A successful operation may leave a warning about configuration that the connector could not honour. used_for: Directing administrators to the setting needing correction. - name: Circuit and rate limits meaning: Admission state records provider failures and allowed call rates. used_for: Preventing excessive work against a failing or limited provider. relationships: - to: CON-PFM-INT-001 statement: A connection belongs to a workspace installation and uses one of that integration’s releases. provenance: observed source: 'services-platform:modules/integrations/services/connections/connection-operations.ts:createConnection' - to: CON-PFM-INT-003 statement: A call selects a connection through a binding or names it explicitly. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/bindings/resolve.integration.spec.js#reaches the processor that took the payment through its named connection - to: CON-PFM-INT-004 statement: Verification provisions the connection’s declared notification endpoints. provenance: test source: >- services-platform:modules/integrations/tests/integration/services/connections/connection-jobs.integration.spec.js#creates one webhook endpoint row per kind the manifest declares, with no secret yet lifecycle: - state: waiting for credential meaning: The account link exists without completed authentication. how_it_changes: 'Credential entry, authorization or discard advances it.' - state: verifying meaning: An account check is in progress. how_it_changes: The check records success or failure. - state: active meaning: The connection is usable and passing checks. how_it_changes: 'Probe results, credentials or staff lifecycle operations change its standing.' - state: degraded meaning: The usable connection has recent failures. how_it_changes: 'Recovery checks, pause or removal can change it.' - state: failed verification meaning: Account verification did not succeed. how_it_changes: 'Staff correct authentication, retry or use the applicable removal path.' - state: needs re-authorization meaning: Authentication must be renewed before use. how_it_changes: An administrator replaces credentials or authorizes again. - state: suspended meaning: A person has paused account use. how_it_changes: Resume or final removal changes its standing. - state: disconnected meaning: The link has ended and its credentials are revoked. how_it_changes: This state is final; a new link uses a new connection. acted_on_by: - CAP-PFM-INT-004 - CAP-PFM-INT-005 - CAP-PFM-INT-006 - CAP-PFM-INT-007 - CAP-PFM-INT-012 - CAP-PFM-INT-013 visible_to: - ACT-PFM-017 - ACT-PFM-018 - ACT-PFM-019 - ACT-PFM-021 - ACT-PFM-006 evidence: - >- services-platform source inventory: modules/integrations/db/integration-connections.table.ts, integration-credentials.table.ts, integration-connection-notices.table.ts, integration-webhook-endpoints.table.ts; services/connections/transition.ts; services/credentials/*; services/health/*; docs/integrations/README.md; docs/milestones/INTG-M1-*. - >- react-console source inventory: components/integrations/connection-wizard.tsx, connection-detail.tsx, connection-facts.tsx; lib/integrations/connection-dot.ts. supersedes: [] --- # Connection ## What It Is A connection is the workspace’s continuing link to an account at a provider. Staff use it to recognize which account Rhythm authenticates against and whether that account can currently serve work. The connection belongs to an installed integration and selects a release of its adapter. It records the authentication method, verified account information, usable features and operational standing. A customer may need several accounts for different business purposes. A connection name helps staff distinguish those purposes, while its stable identifier continues to refer to the account link after a rename. Verification gives the link more meaning than a stored key: it asks the provider which account the credential reaches and what that account supports. An account can also report whether it is a test environment, which is relevant when staff exercise a capability from the Library. ## What It Is Not The connection does not itself determine which business activity uses the account. Bindings make that choice for record, business-unit, application or workspace context. Nor does it replace the provider’s account: it is Rhythm’s record of the link and the authentication needed to reach it. A paused connection and an ended connection represent different administrative intentions. ## How It Is Used Administrators create and verify a link, inspect its health and correct authentication when the provider refuses it. They may pause a usable account, resume it or prepare an upgrade to another release. Before ending a link, they review the work that still selects it. An unfinished initial attempt has a discard path so abandoned setup does not prevent installation removal. Readers use account detail and history to understand the present standing without changing credentials. Applications discover or select a usable account through supported capability context. Rhythm staff investigate broader operational problems. Good use keeps provider account identity, routing choice and observed health distinct: a green account is not proof that it is configured for every business need. ## Its Facets **Status and version pin.** Standing explains authentication, verification, use, pause and removal. The release pin identifies the implementation whose behaviour verification checked. **Authentication.** Entered keys, provider sign-in and a Rhythm-held platform account have different setup paths. Safe facts remain visible while secret values stay outside account reads. **Verified account and features.** These describe the account reached and its supported jobs. Test classification comes from the provider rather than from a customer label. **Health and figures.** Probe results and recent execution statistics help staff investigate whether the account is passing checks and operations are completing. **Endpoints and notices.** Provider notifications use connection endpoints. Connector warnings give administrators a setting-related problem even when an operation succeeded. **Circuit and rate controls.** These protect the selected account during failure or overload without silently assigning its work to another provider. ## How It Relates The integration installation contains the connection, and a gateway execution records the account that actually serves its operation. Routing bindings preserve account choices across business scopes. Endpoints associate incoming notifications with the same account, so removal also closes that notification path. Credential services supply temporary authentication to calls and checks. ## What It Could Become The product should resolve the difference between a deliberately suspended connection and a connection needing intervention in the health summary. OAuth and token renewal are built ahead of their proposed acceptance milestone. Operator rate overrides have persistence support without an exposed staff route. These gaps need separate decisions rather than implying that the presence of an account record proves a complete operational experience.