The connect flow

Your user (a member) connects a provider account once, on Latido's hosted page — like Plaid Link. Your backend never handles provider OAuth: it creates a session, sends the user to its URL and reads the outcome from the redirect.

your backend ──POST /v1/connect/sessions──▶ Latido        → { url, token, expiresAt, memberId }
your app ──redirect──▶ app.getlatido.com/connect/{token}   hosted page: pick a provider
hosted page ──▶ provider consent screen ──▶ api.getlatido.com/connect/callback/{provider}
Latido ──302──▶ your redirectUrl?status=connected&provider=…&connectionId=…

#1. Create the session

POST /v1/connect/sessions (API key) — latido.connect.sessions.create(input)

{
  "data": {
    "token": "cst_…",
    "url": "https://app.getlatido.com/connect/cst_…",
    "expiresAt": "2026-10-27T11:00:00.000Z",
    "memberId": "mem_V1StGXR8_Z5jdHi6B"
  }
}

• The link is valid for one hour. Give the user url, never the token alone.
• Calling again for the same externalUserId makes a new link for the same member; older links stay valid until they expire.
• Which providers are connectable: GET /v1/providers (available: true). In test mode that is only latido_demo, which needs no setup. In live mode a provider needs an enabled provider app in the project (Latido's managed app where the provider allows it, or your own client id and secret) and an adapter in this Latido build. Apple Health and Health Connect are never offered here: they connect through the mobile SDK (mobile-ingest.md).

Errors at this step: REDIRECT_URL_NOT_ALLOWED (400), PROVIDER_APP_NOT_ALLOWED (400 — a requested provider is not connectable in this mode, or the project has none yet), UNPROCESSABLE_CONTENT (422 — the body failed validation).

#2. The hosted page

https://app.getlatido.com/connect/{token} shows your project's name and logo (logoUrl in project settings), the offered providers with the member's current status for each, and a cancel link. It talks to three public, token-scoped endpoints you normally never call yourself:

Starting an authorization puts the member's connection in pending until they come back. For the demo provider the "consent screen" is Latido's own page (https://app.getlatido.com/connect/demo-consent): Allow succeeds, Deny comes back as access_denied.

#3. The redirect

Latido always sends the browser somewhere. With a session, it is your redirectUrl with query parameters appended (existing ones are kept):

reason values sent by the backend:

Parse it with the contract's schema:

const result = latido.connect.parseRedirect(request.url); // or parseConnectRedirect(url)
switch (result.status) {
  case "connected": await saveConnection(result.connectionId, result.provider); break;
  case "error":     showError(result.reason); break;
  case "cancelled": break;
}

When there is no session to read a redirect URL from (an invalid or replayed state, an unexpected failure), the member lands on Latido's own page instead: https://app.getlatido.com/connect/error?reason=invalid_state | session_expired | unexpected_error. Each callback state works once: replaying a callback URL ends on that page.

Do not trust the redirect alone for anything important — it travels through the browser. Confirm with GET /v1/connections/{connectionId} or the connection.created webhook.

#4. After connecting

• The connection turns active, connection.created is sent (connection.updated when an existing connection is re-authorized), and a backfill job fetches the last defaultBackfillDays (project setting, default 30, capped by each provider's maxBackfillDays). backfill.completed follows with per-type counts; a partial failure sends connection.error instead.
• New data then arrives by provider push or polling, each change raising *.created / *.updated events (webhooks.md).
• Statuses (ConnectionStatus): pending, active, expired (the provider refused the tokens — send the member through a new session), revoked (by you or by the member at the provider; tokens wiped), error (the last authorization attempt failed).

Managing a connection:

await latido.connections.get(connectionId);
await latido.connections.sync(connectionId, { days: 14 }); // re-fetch; once per 5 minutes
await latido.connections.revoke(connectionId);              // records stay
await latido.members.delete(memberId);                      // GDPR: connections + all data