Session

A Session is the patient-facing browser flow in Connect. Your backend creates it, receives a URL, and sends the patient there. The patient authorizes access to one or more portals, then returns to your app.

Every Session belongs to one Patient. A Patient can have many Sessions over time because people reconnect, add new sources, or retry failed attempts.

Why Sessions Exist

OAuth is not a single API call. It includes a browser redirect, portal login, consent, code exchange, token storage, and a return to your product. A Session gives that whole flow one durable object.

That object lets your app answer practical questions:

• Is the link still usable?
• Did the patient finish the hosted flow?
• Which source did the patient try to connect?
• Did authorization succeed, fail, expire, or later lose refresh access?

The exact fields live in Create a Connect Session and the usage pages for Picker Mode and Direct Mode.

Lifecycle

open -> complete
open -> expired

open means the patient-facing URL is still valid. complete means the patient finished the browser flow. expired means the URL can no longer be used.

A Session can be complete even if authorization failed. The Session tracks the browser flow. The connection inside the Session tracks the authorization result.

Picker Mode

In Picker Mode, the Session URL opens a Medblocks-hosted search flow. The patient searches for a hospital, payer, or portal, selects the source, signs in, grants access, and lands on a completion screen.

Picker mode is best when you want to ship quickly or do not want to build source search UI yourself.

Direct Mode

In Direct Mode, your app chooses the source before creating the Session. The Session URL sends the patient straight to that portal’s login.

Direct mode is best when source choice belongs in your product, such as trial matching, intake, care navigation, or referral workflows.

Connections Inside A Session

Each authorization attempt creates connection state inside the Session. A connection can be active, failed, expired, or refresh failed.

Active means authorization succeeded and records can flow. Failed means the patient or portal returned an error. Refresh failed means access worked before, but the refresh token stopped working later and the patient needs to reconnect.

Background Pull

The Session ends when the patient finishes the browser flow. Record retrieval continues after that. Medblocks pulls records in the background, refreshes access before tokens expire, and tracks pull progress in the dashboard.

That separation keeps your app responsive. You can show “connected” after authorization, while operational users monitor record availability and exports separately.

Related Articles

• Connect for the full product flow.
• Authorization for OAuth, PKCE, code exchange, and token refresh.
• Picker Mode for hosted source search.
• Direct Mode for your own source search UI.
• After Connection for what to do when the patient returns.