---
id: WF-PFM-INT-003
title: Connect and verify a provider account
trigger: The initiating integration administrator starts this flow.
product_area: platform
module: integrations
revision: 1
status: draft
design_intent: confirmed
implementation_evidence: observed
origin: 'docs/milestones/INTG-M1-find-install-connect.md#Decisions D4, D5 (INTG-M1 Product Accepted)'
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-PFM-INT-004
  - CAP-PFM-INT-005
  - CAP-PFM-INT-013
moves:
  - STATE-PFM-INT-003
  - STATE-PFM-INT-004
  - STATE-PFM-INT-005
crosses: []
idempotency: >-
  Open checks of the same kind reuse their existing job, while every credential entry creates another
  credential.
concurrency: >-
  Transition locking and job lookup prevent duplicate open checks; result updates verify the account’s current
  status.
hops:
  - 'n': 1
    actor_or_service: Integration administrator
    action: Create an account link using authentication supported by an enabled installation.
    anchor: 'services-platform:modules/integrations/services/connections/connection-operations.ts:createConnection'
    seam: sync
    on_failure: Return the refusal to the creation wizard.
    left_inconsistent: The request creates no account link.
    observer: The administrator
    provenance: observed
    source: 'services-platform:modules/integrations/services/connections/connection-operations.ts:createConnection'
  - 'n': 2
    actor_or_service: Integrations service
    action: >-
      Pin the current published release and await authentication, or immediately create verification work for
      a platform account.
    anchor: 'services-platform:modules/integrations/services/connections/connection-operations.ts:createConnection'
    seam: sync
    on_failure: Roll back failed creation.
    left_inconsistent: No incomplete database setup commits.
    observer: The administrator
    provenance: observed
    source: 'services-platform:modules/integrations/services/connections/connection-operations.ts:createConnection'
  - 'n': 3
    actor_or_service: Integration credential administrator
    action: Enter credentials or complete provider authorization for the new link.
    anchor: 'services-platform:modules/integrations/services/credentials/broker.ts:enterCredential'
    seam: sync
    on_failure: Reject fields that do not fit the declared method without logging their values.
    left_inconsistent: 'If secret creation succeeds before database refusal, cleanup is requested separately.'
    observer: The administrator
    provenance: observed
    source: 'services-platform:modules/integrations/services/credentials/broker.ts:enterCredential'
  - 'n': 4
    actor_or_service: Credential store
    action: >-
      Store a new secret, commit credential replacement and check-job records, then request old-secret
      deletion and start verification after commit.
    anchor: 'services-platform:modules/integrations/services/credentials/credential-store.ts'
    seam: sync
    on_failure: Schedule cleanup of the new secret after database failure; failed job startup waits for job recovery.
    left_inconsistent: A committed verification job may still await its start.
    observer: Job monitor
    provenance: observed
    source: 'services-platform:modules/integrations/services/credentials/credential-store.ts'
  - 'n': 5
    actor_or_service: Verification job
    action: Verify the provider account through the adapter using a temporary credential lease.
    anchor: 'services-platform:modules/integrations/services/connections/verify-connection.ts'
    seam: state_machine
    on_failure: Record check failure and its provider reason.
    left_inconsistent: The account is not made usable by a failed first verification.
    observer: The connection page and job history
    provenance: observed
    source: 'services-platform:modules/integrations/services/connections/verify-connection.ts'
  - 'n': 6
    actor_or_service: Verification job
    action: >-
      Save verified account identity, features and environment and activate the link, refusing duplicate live
      account identity.
    anchor: 'services-platform:modules/integrations/services/connections/verify-connection.ts'
    seam: sync
    on_failure: Rollback preserves the prior saved state and fails the check job.
    left_inconsistent: A repeated check can contact the provider again.
    observer: The connection page
    provenance: observed
    source: 'services-platform:modules/integrations/services/connections/verify-connection.ts'
  - 'n': 7
    actor_or_service: Endpoint hook
    action: >-
      Provision endpoint secrets and request provider registration where the notification declaration uses API
      setup.
    anchor: >-
      services-platform:modules/integrations/services/webhooks/webhook-registration.ts:provisionWebhookEndpoints
    seam: sync
    on_failure: An unsuccessful provider setup leaves no saved provider endpoint reference.
    left_inconsistent: Rhythm can hold an endpoint that the provider has not begun calling.
    observer: Webhooks screen
    provenance: observed
    source: >-
      services-platform:modules/integrations/services/webhooks/webhook-registration.ts:provisionWebhookEndpoints
evidence:
  - >-
    services-platform at ad3f6a65: modules/integrations/services/connections/connection-operations.ts,
    submit-connection-jobs.ts, verification-workflow.ts, verify-connection.ts;
    services/credentials/credential-store.ts, broker.ts; services/webhooks/webhook-registration.ts
  - 'react-console at baf6dae3: components/integrations/connection-wizard.tsx'
  - >-
    services-platform:modules/integrations/tests/e2e/integrations.e2e.spec.js#connects a platform account,
    which starts verifying with its job
  - >-
    services-platform:modules/integrations/tests/e2e/integrations.e2e.spec.js#connects a platform account,
    which starts verifying with its job
  - >-
    services-platform:modules/integrations/tests/e2e/credential-entry-limits.e2e.spec.js#INT-ACC-0166 step 5:
    refuses a value of 8193 characters with 400 naming the field and the limit, and stores nothing
  - 'services-platform:modules/integrations/services/credentials/credential-store.ts:verification_retried'
  - >-
    services-platform:modules/integrations/tests/integration/services/connections/connection-jobs.integration.spec.js#becomes
    active with the account and every declared feature verified
  - >-
    services-platform:modules/integrations/tests/integration/db/integration-connections.table.integration.spec.js#refuses
    the same provider account connected twice under the installation
  - >-
    services-platform:modules/integrations/tests/e2e-adapters/events-dummy.adapters.spec.js#never answers the
    secret again
controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, 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-IAM-006, 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-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]
---

# Connect and verify a provider account

## What It Does

Account setup establishes which provider account the credential reaches before the gateway can use it. Secret storage and the database have separate failure boundaries. Durable verification records explain success or the reason setup failed.

## The Flow

```mermaid
sequenceDiagram
  participant P0 as Integration administrator
  participant P1 as Integrations service
  participant P2 as Integration credential administrator
  participant P3 as Credential store
  participant P4 as Verification job
  participant P5 as Endpoint hook
  P0->>P0: 1. Create an account link using authentication supported by an enabled installation.
  P1->>P1: 2. Pin the current published release and await authentication
  P2->>P2: 3. Enter credentials or complete provider authorization for the new link.
  P3->>P3: 4. Store a new secret
  P4->>P4: 5. Verify the provider account through the adapter using a temporary credential lease.
  P4->>P4: 6. Save verified account identity
  P5->>P5: 7. Provision endpoint secrets and request provider registration where the notification declaration uses API setup
```

## When Something Fails

Return the refusal to the creation wizard. The request creates no account link. Roll back failed creation. No incomplete database setup commits. Reject fields that do not fit the declared method without logging their values. If secret creation succeeds before database refusal, cleanup is requested separately. Schedule cleanup of the new secret after database failure; failed job startup waits for job recovery. A committed verification job may still await its start. Record check failure and its provider reason. The account is not made usable by a failed first verification. Rollback preserves the prior saved state and fails the check job. A repeated check can contact the provider again. An unsuccessful provider setup leaves no saved provider endpoint reference. Rhythm can hold an endpoint that the provider has not begun calling.

## Open Design Questions

The browser acceptance evidence does not prove wrong-key recovery within the wizard. Endpoint registration can leave a local endpoint that the provider does not call.