Connection Flow

Understanding the connection lifecycle is essential for building a smooth user experience.

Overview

A connection represents a linked bank account. The flow to create one involves your backend, frontend widget, and Araucaria's servers working together.

sequenceDiagram participant U as User participant F as Your Frontend participant B as Your Backend participant A as Araucaria API participant Bank as Bank U->>F: Click "Connect Bank" F->>B: Request widget token B->>A: POST /v1/connections A-->>B: { connectionId, widgetToken } B-->>F: { connectionId, widgetToken } F->>F: Open Araucaria Widget U->>F: Select bank & enter credentials F->>A: Submit credentials A->>Bank: Validate credentials Bank-->>A: Success A-->>F: Connection CONNECTED F->>U: Show success A->>B: Webhook: connection.connected B->>B: Process new connection

Step-by-step Flow

Create connection - Your backend calls POST /connections to get a widget token
Open widget - Your frontend initializes the widget with the token
User authenticates - User selects their bank and enters credentials
Credentials verified - Araucaria validates with the bank
Webhook notification - Araucaria sends a webhook to your backend when the connection is connected

Re-credential Flow

When credentials fail — either on first attempt or after a previously successful connection — the system handles recovery depending on whether the connection has historical data.

Scenario A: New Connection, Wrong Credentials

The user enters wrong credentials on their first attempt. The widget shows two options:

Retry — Goes back to the credential form. The user can correct their credentials and re-submit.
Cancel (Abandon) — Deletes the connection entirely since it has no historical data.

No API changes are needed from your side — the widget handles this internally using the original widget token.

Scenario B: Established Connection, Credentials Expire

A connection that was previously CONNECTED fails authentication during a re-sync (e.g., user changed their bank password). The connection transitions to FAILED_AUTH.

sequenceDiagram participant B as Your Backend participant A as Araucaria API participant W as Widget (Browser) participant Worker as Worker Worker->>A: Re-sync fails → FAILED_AUTH A->>B: Webhook: connection.failed_auth B->>A: POST /connections/:id/widget-token (API Key) A-->>B: { connectionId, widgetToken, institutionId } B->>W: Open widget with new token W->>A: GET /status → institutionId set W->>W: Skip institution select, show credential form W->>A: POST /credentials (new creds) A->>Worker: Publish sync job Worker->>A: Transition → CONNECTED A-->>W: Poll → status: CONNECTED

💡 Delete Protection

Connections that have successfully synced data (lastSyncedAt is set) cannot be deleted. Attempting to delete returns a 409 CONNECTION_HAS_DATA error. Use the re-credential flow or transition to DISCONNECTED instead.