Operator-required cleanup
Use this workflow only when a connection is in operator_action_required. This state means the wrapper cannot prove both the local connection state and every remaining provider authority. The dashboard blocks connection changes until an operator resolves that ambiguity. Revoking a device does not revoke recipient grants created by that device.
An authenticated read rejection or failed credential refresh does not enter this state. It enters reconnect_required, where the customer can select Reconnect and sign in to the same Perflo account. A successful reconnect preserves the provider binding and restores service without an operator.
This workflow protects authorities that a device lookup cannot resolve. Skipping a step, broadening the SQL predicate, or treating a timeout as confirmation can orphan a Perflo device, recipient grant, or payment result. Read every step before running it.
When this applies
A connection enters operator_action_required when connection cleanup or local credential persistence becomes indeterminate and automated verification cannot recover it. The request may or may not have reached Perflo, or the local row may not describe provider state with confidence. The customer dashboard disables Connect, Disconnect, and Resume until an operator completes this workflow.
The wrapper retains the device_id and any cleanup ciphertext it can persist. A simultaneous Vault failure can leave no usable ciphertext, which is one of the cases the backup requirement below addresses.
Old-device cleanup after a same-account reconnect follows a different path. Before submitting revocation, the wrapper durably changes the cleanup to operator_action_required with device_revocation_in_progress; a process exit or local commit failure therefore cannot replay the provider write. Perflo success resolves the cleanup, while a definitive rejection that proves revocation was not accepted reopens it for a later credential attempt. A definitive credential rejection may be retried with an active credential belonging to the same customer and Perflo subject. A transport-uncertain revocation is never retried and remains operator_action_required. If a customer signs in to the wrong Perflo account during recovery, the wrapper rejects that identity and retains its encrypted access credential for cleanup. When Perflo omits that candidate’s device ID, selector-less revocation uses only that retained credential; it never falls back to the replacement credential. Those cleanup records do not block recovery unless their identity or revocation result is unprovable.
The workflow
Why this is not an API endpoint
The API does not expose this destructive binding deletion. The operator role can inspect and suspend activity but cannot assert grant revocation, settle an indeterminate payment, or clear credentials. Those actions require exact Perflo evidence that the device lookup cannot provide. The guarded SQL workflow remains the supported path for operator_action_required; ordinary credential recovery belongs to the customer reconnect flow.
- Operator console: the read-and-suspend surface operators use to
identify the connection and
request_id.
- Backups & recovery: the volume set to back up before step 3, and
the rule against
docker compose down --volumes on an active connection.
- Vault: why losing either Vault volume makes stored Perflo ciphertext
unrecoverable.