Links

Links are the core abstraction in the Connect Service — a lightweight intent to connect a user’s account.

What is a link?

A link represents a request to perform one or more operations on a user’s account with a specific integration. Inspired by Plaid’s link_token pattern, links are cheap to create and only spawn sessions when claimed.

Each link targets an integration and one or more operations:

• integrationId — The service (e.g., tmobile, att)
• operations — An ordered list of { resource, action, arguments? } tuples

For example, a single link can read payment methods and then write a new one — both in the same session, with the user logging in only once. Operations execute sequentially; if any operation fails, the entire link fails.

Lifecycle

1. Pending — POST /v1/links creates a link record with a claim code
2. Active — The client SDK calls POST /link/claim with the claim code, creating a session and starting the automation
3. Complete — The automation finishes successfully; result data is stored on the link
4. Failed — The automation encountered an error; the link can be re-claimed for a new attempt
5. Expired — The link expired before being claimed or completed (4-hour TTL)

Re-claiming

If a link fails, the user can try again. Each claim creates a new session — the link itself persists across attempts. Every session attempt is recorded in the link_sessions table, so failed sessions remain visible for debugging even after the link is re-claimed with a new session.

Return URL

You can optionally pass a returnUrl when creating a link. After the session completes, the client SDK redirects the user to this URL. Both https:// URLs and custom app schemes (e.g., myapp://callback) are supported — useful for deep-linking back into your app after the flow finishes.

The backend automatically appends linkId as a query parameter to the URL returned in API responses. For example, https://your-app.com/done becomes https://your-app.com/done?linkId=link_abc123, and myapp://callback?ref=foo becomes myapp://callback?ref=foo&linkId=link_abc123.

Single-use on success

Once a link completes successfully, it cannot be re-claimed. Create a new link for subsequent account connections.

Next steps

• Sessions — What happens after a link is claimed
• Create Link API — API reference