Connect

Connect is the hosted ceremony where a user authorizes access to a health system (EHR). It runs in the user's browser via a popup; your API key never enters the browser.

Recommended integration

Two one-line mounts and zero graduation logic in your app code.

1. Mount the server proxy once (e.g. app/api/curaeai/[...curaeai]/route.ts):

import { createCuraeAIRouteHandlers } from '@curaeai/platform-sdk/server';
import { auth } from '@/lib/auth';

export const { GET, POST } = createCuraeAIRouteHandlers({
  apiKey: process.env.CURAEAI_API_KEY!,
  baseUrl: process.env.CURAEAI_BASE_URL,
  resolveAppUserId: async () => (await auth())?.user?.id ?? null,
});

2. Wrap your app once (inside your auth gate):

import { CuraeAIAccountProvider } from '@curaeai/platform-sdk/react';

<CuraeAIAccountProvider appUserId={session.user.id}>
  {children}
</CuraeAIAccountProvider>;

3. Gate on isReady:

import { useCuraeAIAccount } from '@curaeai/platform-sdk/react';

function Feature() {
  const { isReady } = useCuraeAIAccount();
  if (!isReady) return null; // provider renders the upgrade UI automatically
  // …safe to call connection-scoped APIs.
}

The provider detects a LIMITED account, renders the upgrade prompt at the right moment, sends the user through the Curae-hosted graduation, and reconciles state on return — so the LIMITED → ACTIVE graduation needs no code in your app.

The widget directly

If you're not using the provider, render the button and host a proxy yourself. The widget POSTs an empty body to connectEndpoint; your proxy injects the key, forwards to /api/sdk/v1/connections, and returns the JSON verbatim.

import { CuraeConnect } from '@curaeai/platform-sdk/react';

<CuraeConnect
  connectEndpoint="/api/curaeai/connections"
  onSuccess={({ connection }) => {
    // connection.status: AUTHORIZED, or PENDING for a silent LIMITED
    // connection a webhook will later promote.
  }}
  onExit={() => {/* user dismissed the popup */}}
/>;

A framework-agnostic web component (<curae-connect-button>) is available from @curaeai/platform-sdk/connect for non-React apps.

What you get back

A connection has a lifecycle the platform keeps you in sync with via webhooks: connection.authorized, connection.reconnected, connection.expired, connection.action_required, connection.revoked. Cache the connectionId; use it for record reads and exports.

Next

• Webhooks — react to connection + data events.
• API reference — the /api/sdk/v1/connections contract.