LifeCare.ID® Developer Docs Public

API reference ✅

The complete endpoint catalogue available today. This page is a human-readable companion to the machine-readable contract, the authoritative, drift-tested source is docs/contracts/openapi.json (regenerated on every API change and enforced by tests). Import that file into Postman / Swagger / your codegen.


Identity (L1) ✅

Method Path Purpose
POST /v1/identity/register Register a P-256 public key → derive DID, return DID document
POST /v1/identity/register/begin WebAuthn registration: creation options
POST /v1/identity/register/finish Verify attestation → DID + session
POST /v1/identity/auth/begin WebAuthn sign-in: request options
POST /v1/identity/auth/finish Verify assertion → session
GET /v1/identity/resolve/{did} Resolve a DID document
GET /u/{user_id}/did.json Standard did:web resolution path
GET /agent/{agent_id}/did.json Reserved agent namespace; always 404 agent identities are not yet supported
POST /v1/identity/rotate Trust-partner-approved key rotation (header X-Trust-Partner-Token; fail-secure). Also ends every native app connection (refresh-token family) of the DID
POST /v1/identity/session/verify Resolve a session token → {active, did, expires_at}
POST /v1/identity/session/logout Revoke a session token (and, for a session a native app's refresh token minted, that whole connection)
POST /v1/identity/pairing/exchange A native app adopts the identity a signed-in client paired to it: single-use pairing token → session. Naming a registered native client_id also returns a rotating refresh_token (Authentication)
POST /v1/identity/refresh/admin/revoke Operator: end a member's native app connections (all, or one client_id's) and the sessions they minted (header X-Trust-Partner-Token; fail-secure)

Register example:

POST {base}/v1/identity/register
{ "public_key_jwk": { "kty": "EC", "crv": "P-256", "x": "…", "y": "…" },
  "terms_version": "2026-09-07", "age_confirmed": true }
→ { "did": "did:web:…", "created": true, "did_document": { … } }

DID derivation: did:web:<domain>:u:<first-16-hex-of-RFC7638-thumbprint>. Registration is idempotent by key (created:false if already known).

Terms acceptance (contract 0.13.0). Creating an identity requires the person's acceptance of the member terms and privacy notice: terms_version (a version string the service knows, currently 2026-09-07) and age_confirmed (they are 18 or older). Both are stored against the identity; a missing, unknown, or negative acceptance is 422 and creates nothing. POST /v1/identity/register/finish takes the same two fields, optional in the schema and required whenever the ceremony would create a new identity, an existing DID re-binding a passkey keeps the acceptance it already has. Identities created before this landed carry no acceptance, and nothing backfills them.

The first recovery email travels inside the ceremony. Creating an identity asks for the passkey once, and the person's first recovery email comes with it: send recovery_email to POST /v1/identity/register/begin, which binds the exact address (trimmed, lower case) into the ceremony's single-use challenge (the SHA-256 of canonical JSON {"email", "form": "lifecareid-registration-recovery-email-v1", "nonce"}), and send the same address to POST /v1/identity/register/finish. Finish stores it as the identity's first, unconfirmed recovery email and mails its one-tap confirmation link; the response carries recovery_email (email masked, sent). An address that differs at finish from the one bound at begin, or that appears on only one side, is 403 and creates nothing; a malformed address is 422 at begin. If the confirmation link cannot be handed to the mailer, the identity and its passkey are created and sent is false: the address is not kept, and the person sets it with POST /v1/recovery/email and their passkey. With the deployment setting LIFECAREID_REQUIRE_RECOVERY_EMAIL on, a ceremony that would create a new identity without a recovery email is 422 and creates nothing. On the sandbox the field is set aside and nothing is required.

Reserved namespaces. u: is the only principal kind served today. Two more are reserved so a third principal type never has to be retrofitted into token and ledger schemas: did:web:<domain>:node:<id> (a node's own identity) and did:web:<domain>:agent:<id> (a personal agent, see Agent trust), the latter resolving at /agent/{id}/did.json. Neither can be registered or resolved yet; both answer 404 with "<kind> identities are not yet supported", so a caller gets a straight answer rather than a guess.


Recovery (L1) ✅

Email-magic-link recovery (beta trust anchor). Primarily an end-user / web-surface flow; listed for completeness.

Method Path Purpose
POST /v1/recovery/email/begin Open the passkey ceremony for one address (session-auth) → assertion options
POST /v1/recovery/email Enroll a recovery email (session-auth plus the person's passkey assertion over that address) → verify link
POST /v1/recovery/email/verify Confirm the email from the link
POST /v1/recovery/email/status Masked email + verified flag (session-auth)
POST /v1/recovery/begin Start recovery from an email → recovery link
POST /v1/recovery/finish New passkey + recovery token → rotate key, new session

Setting or replacing a recovery email takes the person's passkey. A session alone is refused with 403 and nothing is written. POST /v1/recovery/email/begin (session_token, email) returns ceremony_id and WebAuthn request options: the person's own passkeys, user verification required, and a challenge bound to the person and that exact address. Pass the options to navigator.credentials.get(), then send session_token, email, ceremony_id and the assertion (credential, JSON form) to POST /v1/recovery/email. The ceremony is single use and lasts 300 seconds. An identity with no passkey cannot set a recovery email.

The first recovery email is pending until its link is confirmed, then recovers the account. It is normally set at creation, inside the registration ceremony (see Identity above); an identity with none adds one here, with its passkey. If a mail this route sends (a confirmation link, or the notice to a confirmed address) cannot be handed to the mailer, it answers 502 and nothing is recorded: no address, no waiting replacement, no live link. A replacement for a confirmed address does not touch it: the confirmed address is told at once, the new one is confirmed by its own link, and then it waits (seven days by default, LIFECAREID_RECOVERY_EMAIL_CHANGE_WAIT_SECONDS) before it recovers the account. During the wait the confirmed address still recovers the account, and a recovery cancels the waiting replacement. While a replacement waits, POST /v1/recovery/email/status adds pending (email masked, confirmed, usable_at), and confirming its link answers usable_at. On the sandbox the routes that set an address or start a recovery answer 404: POST /v1/recovery/email/begin, POST /v1/recovery/email, POST /v1/recovery/begin and the /recover page.


Method Path Purpose
POST /v1/consent/grant Create a grant → {consent_id, receipt}. Optional proof, a WebAuthn assertion over the grant digest, verified whenever present
POST /v1/consent/revoke Revoke a grant → kills tokens, ledgers it
GET /v1/consent/grants/{did} All grants for a DID (receipts). With caller authentication required: the person or a first-party client
GET /v1/consent/ledger/{did} Full hash-chained ledger {chain_valid, entries[]}. With caller authentication required: the person alone
POST /v1/access/record Record a data access (resource-host audit). Names the reader with actor_did (preferred, must be a DID) or the legacy free-text accessor; one is required. A signer's DID must match the actor_did it asserts (403). With caller authentication required, a client that is not first party records only under a grant it served: send the consent_id from introspecting the token (who may record an access), else 403

The credential an app presents for a member on grant, revoke, grants and ledger is the member's session, Authorization: Bearer lcs_...; on the hosted sandbox the synthetic identity's session_token is that credential.

See Scopes & consent for field-level detail, the receipt shape, and how a device proof is constructed. Scopes: cgm, daily, labs, body_composition, recovery, activity, insights, told_to_guardian. A grant naming a grantee in LIFECAREID_MEMBER_ONLY_GRANTEES (the person's guardian) is accepted only from the person themselves, never from a client credential (details).

Caller authentication (the four write endpoints and the two reads). /v1/consent/grant, /v1/consent/revoke, /v1/access/record, /v1/token, /v1/consent/grants/{did} and /v1/consent/ledger/{did} accept a holder signature (X-LifeCare-Signature, the scheme under Resource registry below), confidential-client credentials (Authorization: Basic, or client_id + client_secret in the body), or the person's own session (Authorization: Bearer lcs_...). A signature or client credential you present is always verified; whether an unauthenticated call is accepted, and who may act for whom, is a deployment setting (LIFECAREID_REQUIRE_CALLER_AUTH, default off). See Authenticating your calls for the rules and the rollout.


Authorization / tokens (L3) ✅

Method Path Purpose
POST /v1/token Issue a data-access token (RPT) against a matching grant. Credential: the member's session (Authorization: Bearer lcs_...), client credentials or a holder signature; a session is issued a token only against a grant to the member or their first party (a person's own script); an app gets its token from the authorization code flow. Optional purpose_dpv matches the grant on its DPV term instead of exact text. An authenticated caller's requester must be its own identity, client id or signer DID (403)
POST /v1/token/introspect Validate a token → claims or {active:false}. Requires your client credentials (HTTP Basic, or client_id + client_secret in the body; RFC 7662 §2.1): no credential 401, a session or holder signature 403, both before the token is looked up. token_type:"access" carries resource_owner + scope (and aud on a token from the authorization code flow, and on a first-party token where the deployment names its first party's resource); token_type:"user" carries subject_did. A third shape, token_type:"delegated", is published and never issued: fail closed on any type you do not implement
GET /v1/revocation/{user_id} Public revocation registry for a subject

See Authorization & tokens (developer access).

Sandbox-only routes (POST /v1/sandbox/clients, GET and DELETE /v1/sandbox/clients/{client_id}, POST /v1/sandbox/test-identity) are outside the contract; see Sandbox.


Method Path Purpose
GET /v1/panel/summary Identity + active grants
GET /v1/panel/feed Reverse-chron ledger feed; ?category=&limit=&before=
POST /v1/panel/grant Grant as the session user (no subject_did)
POST /v1/panel/revoke Revoke (ownership-checked)
GET /v1/panel/resources The user's current ownership-and-location map (L2b, below)

See Embedding the consent panel.


Resource registry (L2b) ✅

What exists about the user, who holds it, where, the counterpart to consent's who may read it. Written by holders (the user's own node, a holder the user granted, the user's own device), read by the user, and by each holder for its own entries only.

Method Path Purpose
POST /v1/registry/record A holder registers / versions / tiers / moves / shreds / deletes one resource it holds. Idempotent on (subject_did, holder.id, resource_id, event, manifest.content_hash); a replay returns the existing entry_hash. Who may write what: see below
GET /v1/registry/{did} Chained history, newest first; ?limit=&before=<entry_hash>; returns chain_valid for the page. The user reads all of it, a signed holder only its own entries (see below)
GET /v1/panel/resources The user's current map grouped by holder (session token), with erased per holder

The entry. subject_did, resource_id, kind (raw_at_source|derived|twin_artifact|copy), category (the strict ResourceCategory vocabulary in the contract), holder{id, role}, location{kind, ref}, event (registered|versioned|tiered|moved|shredded|deleted), optional consent_id, optional manifest{version, content_hash, recipe} (never for raw_at_source), optional supersedes. Status is derived from the event, never sent.

Zero-PHI at the boundary. Every field is an enum, a regex-typed identifier, a sha256 hash, a version token or a registry timestamp; there is no free-text and no numeric field anywhere on the entry. Unknown JSON keys are rejected (422), not dropped, and unknown categories are rejected, the vocabulary grows by contract bump, never by payload.

Who writes. POST /v1/registry/record admits its parties alone, in every deployment:

Caller Writes
the user's own node: a client named in LIFECAREID_FIRST_PARTY_CLIENTS, with its client credential (HTTP Basic) its own entries (holder.id is its client id), in any holder.role but user_device, and source entries (holder.role: source, a provider id such as withings as holder.id, never a DID), for any user
a holder, signing with X-LifeCare-Signature (below) only entries whose holder.id is the DID that signed, in any holder.role but home_node and user_device, and only for a user who has an active grant (not revoked, not expired) naming that DID as grantee.id
the user (their session, Bearer lcs_..., or a signature by their own DID) only their own user_device entries (holder.id their DID)
anyone else nothing: 401 with no credential, 403 for any other caller, both before the DID is looked up and before anything is written or ledgered

A holder that writes for a user asks that user for a grant first; the grant's scope does not matter, its grantee does. An admitted write for a subject LifeCare.ID® does not know is 404 "unknown subject DID".

Who may claim each role. The user's ledger reads each holder.role as a sentence ("Your home node now keeps ...", "Your device ..."), so two roles belong to the user's own things: only the user's own node writes home_node, and only the user's own device writes user_device.

holder.role the user's own node a holder the user granted the user's own device
source yes: its own entries, and source entries naming a provider yes no
home_node yes no no
replica yes yes no
user_device no no yes
ehr yes yes no
external_holder yes yes no

A role the caller may not claim is 403, with a detail that names the rule (for example "only the member's own node (a first-party client) may write home_node entries ..."), before the DID is looked up and before anything is written or ledgered. A holder writes in the role that says what it is: a replica it keeps, an ehr that is a practice's system of record, an external_holder outside the network, or a source.

Who reads the history. GET /v1/registry/{did} answers its parties alone, in every deployment:

Caller Reads read_as
the user (their session, Bearer lcs_..., or a signature by their own DID) every entry subject
a holder, signing with X-LifeCare-Signature (below) only the entries whose holder_id is the DID that signed; an empty page if it holds nothing for this user, whether or not the DID exists holder
anyone else nothing: 401 with no credential, 403 for any other caller (another user's session, any client), both before the DID is looked up

A holder signs the GET like a write, over an empty body. Its before cursor must be one of its own entries' entry_hash. Its chain_valid checks each entry it is shown against that entry's real predecessor in the user's chain, so it means what it means in the user's view: every entry shown sits, unaltered, at its place in the chain. Each entry keeps its real prev_hash, which may be the hash of another holder's entry; the entry itself is never shown.

Erasure proof. A holder completes an erasure by writing shredded for each of its entries. The panel's erased flag is computed from the registry, a holder is erased for a user exactly when none of its entries is active or tiered.

Holder signing. Both /v1/registry/record and /v1/access/record accept:

X-LifeCare-Signature: keyid="<holder DID>",alg="ES256",created=<unix>,sig="<base64url r||s>"

signed over METHOD\npath\ncreated\nsha256(body) (UTF-8, newline-separated) and verified against the key LifeCare.ID® publishes for keyid. created must be within 300 s. A presented signature is always verified. On /v1/access/record, whether an unsigned holder write is accepted is a deployment setting (LIFECAREID_REQUIRE_HOLDER_SIGNATURE, default off). The registry write does not read that setting: who may write there is the table above, in every deployment.


Federation: signing a person in through LifeCare.ID® ✅

Browser-redirect + form handshake on the LifeCare.ID® origin. Not in the JSON contract (it's a redirect/form surface), but stable and documented in Authentication.

Method Path Purpose
GET /authorize OAuth authorization request (code + PKCE S256). With one data scope, an RFC 8707 resource, and optionally purpose and purpose_dpv (sandbox, behind a setting), it ends in the person's grant question on the issuer origin
POST /data-consent/decide The person's answer to the grant question (issuer origin only; sandbox, behind a setting). A yes makes a single-scope grant naming the client as grantee, for the asked 30 days or, behind LIFECAREID_OAUTH_CONSENT_NARROWING (arriving), the shorter term the person chose (term_days: 30, 7 or 1; with an identical grant standing also keep, sooner-30, sooner-7, sooner-1; any other value is invalid_request; keep and sooner- values are refused when no grant stands; never longer), or reuses an identical one, and redirects with a code. When the deployment requires a passkey proof for the grant (LIFECAREID_REQUIRE_GRANT_PROOF, arriving), the page's script adds proof, the person's WebAuthn assertion over the terms; a yes without a valid one is access_denied and writes nothing
GET /.well-known/oauth-authorization-server, /.well-known/openid-configuration The issuer's metadata (RFC 8414 and OpenID); on the sandbox it lists the seven data scopes and authorization_response_iss_parameter_supported
POST /token Code exchange → {did, access_token} (a native public client also receives refresh_token); grant_type=refresh_token renews a native app's session and rotates its refresh token. For a code from the grant question it returns an lc_ data-access token with aud instead, and no session
POST /revoke RFC 7009 revocation: a native app's sign-out ends its connection
GET /, /signin, /recover, /verify-email LifeCare.ID® web surface pages
POST /session, /session/handoff, /session/establish Set the session cookie on the LifeCare.ID® origin (__Host-lc_id_session on https). Both the federation form-POST and the in-place /session take a one-time handoff code bound to the browser, never a session token; the form returns only to a same-origin path
POST /session/logout, GET /logout End a session (RP-initiated logout honors registered origins)

Service

Method Path Purpose
GET /healthz Liveness probe → {status:"ok", service:"lifecareid"}
POST /v1/notify/operator The user's own node reports an operational event (a new error fingerprint, an outbound failure) to the operator's fixed alert address: {subject, text}, operational text only, never health data. Only a client named in LIFECAREID_FIRST_PARTY_CLIENTS, with its client credential (HTTP Basic): 401 with no credential, 403 for any other caller, before anything is sent, in every deployment. {sent:false, reason:"no_operator_email"} where no address is configured. Not a route for apps
GET /healthz/deep Whether the way out works → 200 {ok:true, checks:{mail_relay:"ok"}} or 503 {ok:false, checks:{mail_relay:"fail"}}. The mail relay resolves and answers (no secret, no mail sent); runs at most once a minute, answers within about four seconds, Cache-Control: no-store, no host or error text in the body

Conventions