Initiate a Curae Connect entry-flow session (Path A / B / C selection)
Mints a fresh CuraeConnectSession for the SDK app's (customerAccountId, appUserId) coordinate. Path selection is deterministic from the bound `LimitedAccountAppBinding`: existing-ACTIVE → Path A (`EXISTING_ACTIVE_HANDOFF`, handoff lands in-tx), no-binding + `preferSignup: true` → Path B (`NEW_ACTIVE_SIGNUP_HANDOFF`, requires `completeHandoff`), else → Path C (`SILENT_LIMITED`, reuses or provisions a LIMITED user). The route requires `connection:write` scope and an `Idempotency-Key` (retries replay the original response verbatim). Rate-limited at 10 req / customer-account / appUserId / minute on top of the standard Platform API buckets.
/api/sdk/v1/curae-connect/initiateMints a fresh CuraeConnectSession for the SDK app's (customerAccountId, appUserId) coordinate. Path selection is deterministic from the bound LimitedAccountAppBinding: existing-ACTIVE → Path A (EXISTING_ACTIVE_HANDOFF, handoff lands in-tx), no-binding + preferSignup: true → Path B (NEW_ACTIVE_SIGNUP_HANDOFF, requires completeHandoff), else → Path C (SILENT_LIMITED, reuses or provisions a LIMITED user). The route requires connection:write scope and an Idempotency-Key (retries replay the original response verbatim). Rate-limited at 10 req / customer-account / appUserId / minute on top of the standard Platform API buckets.
Authorization
platformApiKey CuraeAI Platform API key using the format Bearer . Keys are opaque credentials such as cae_live_..., not JWTs.
In: header
Header Parameters
Required idempotency key for safe initiate retries.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
curl -X POST "https://example.com/api/sdk/v1/curae-connect/initiate" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "appUserId": "string" }'{ "session": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0", "customerAccountId": "d8c60791-7301-441c-98e8-5bea9a162d9b", "appUserId": "string", "subjectUserId": "296d2d93-03fc-4d0e-b7e7-4f7600664125", "state": "INITIATED", "handoffReturnUrl": "http://example.com", "deviceKeyCnf": {}, "ttlExpiresAt": "2019-08-24T14:15:22Z", "createdAt": "2019-08-24T14:15:22Z", "completedAt": "2019-08-24T14:15:22Z" }, "path": "EXISTING_ACTIVE_HANDOFF", "subjectUserId": "296d2d93-03fc-4d0e-b7e7-4f7600664125", "createdLimitedAccount": true, "handoffToken": "string", "handoffTokenExpiresAt": "2019-08-24T14:15:22Z"}{ "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "details": {}, "retryable": true}Reconnect an SDK patient connection POST
Starts a connection lifecycle recovery flow for an expired, revoked, or action-required SDK connection. Active and pending connections are not reconnected.
Mint a graduation handoff token for an existing LIMITED user POST
SDK consumers surface a `<CuraeUpgradeCard>` whenever the current user is in the `LIMITED` lifecycle state; a tap on the upgrade CTA proxies to this route via the consumer backend. The platform mints a fresh server-signed `GRADUATION_HANDOFF` JWT that pins the LIMITED `User.id` and returns the Curae-hosted `/graduate?handoff=<token>` webview URL the SDK navigates the user to. The credential-binding ceremony (passkey, magic link, password) runs inside that webview. Idempotency-Key is REJECTED because every call MUST mint a fresh short-lived JWT — replays would return a stale token whose TTL may have elapsed. Rate-limited at 10 req / customer-account / appUserId / minute (same cap as `/initiate`) to close the LIMITED-binding enumeration side channel.