LifeCare.ID® Developer Docs Public

Sandbox ✅

Engage with LifeCare.ID® without requesting access. The sandbox is an isolated instance where you self-register an app and mint a synthetic signed-in user in seconds, then run the full sign-in to grant to token to introspect loop. It holds only synthetic, zero-PHI data, and it is separate from production.


1. Register your app (self-service)

On the hosted sandbox, pass your developer access token (from the portal, https://app.lifecare.id/devaccess) as a Bearer.

DEVACCESS=…   # the token from https://app.lifecare.id/devaccess (the portal's verify page)
curl -s -X POST "$SANDBOX/v1/sandbox/clients" \
  -H "Authorization: Bearer $DEVACCESS" \
  -H "Content-Type: application/json" \
  -d '{"name":"My app","redirect_uris":["http://127.0.0.1:4000/callback","http://localhost:4000/callback"]}'
{
  "client_id": "sbx_Zy47k_NDW4E",
  "client_secret": "qDkujP10i72…",
  "redirect_uris": ["http://127.0.0.1:4000/callback", "http://localhost:4000/callback"],
  "resources": [],
  "note": "Sandbox client. Store the secret now - it is not shown again."
}

You now have a client_id and client_secret, the same credentials an operator would otherwise issue you. redirect_uris is required (at least one, even for a server's client that never redirects; any loopback URL will do) and is an exact-match allowlist: pass every callback URL you will use. The redirect URI your client sends to /authorize must be one of them, byte for byte; localhost and 127.0.0.1 are different strings, and anything else is a 400 page, not a redirect.

Name your own server as a resource

If you are building a server that reads on a person's behalf (a data source, an MCP server), register its address on a client so a token can be issued for it. Add resources, one to five absolute URLs, to the registration:

curl -s -X POST "$SANDBOX/v1/sandbox/clients" \
  -H "Authorization: Bearer $DEVACCESS" \
  -H "Content-Type: application/json" \
  -d '{"name":"My server","redirect_uris":["http://127.0.0.1:4000/callback"],
       "resources":["http://127.0.0.1:8787/mcp"]}'

The answer repeats them as "resources": ["http://127.0.0.1:8787/mcp"]. A resource is https on any host, or http on a loopback host (127.0.0.1, localhost or [::1]) for your own machine; it has no fragment and no credentials in the URL, and is at most 512 characters. Anything else answers 422.

On the hosted sandbox (since 2026-11-04, contract 0.27.0), a resource you register is accepted as the RFC 8707 resource of an /authorize request for a data scope from any of your own clients: the server's client and your agent's client can be different clients, as long as both were registered with developer access tokens for the same email. The match is on the exact URL, with no wildcard and no path prefix. The token's aud is that URL. A resource you registered is never accepted for another developer's client. That is only half of it: another developer can register the same address on their own clients and obtain a token whose aud is your server, so your server still decides which clients it accepts, by the token's grantee (requester on introspection; the library's grantees option is required for this reason). The sandbox source's own address stays available to everyone. (A production instance accepts only the resources its operator lists; it has no self-service registration.)

Two things to get right. Clients registered before 2026-11-04 (contract 0.27.0) carry no owner, and can neither hold a resource nor ask for one on the hosted sandbox: register both the server's client and the agent's client again, after that date, with developer access tokens for the same email. And register exactly the string your server names as its resource, byte for byte. Copy the resource value from your server's own protected resource metadata (curl -s <your origin>/.well-known/oauth-protected-resource/<path>) into resources; with the library that is pma.resource. The issuer matches the stored string, while the library lower-cases the host and drops a default port and a trailing slash, so http://LOCALHOST:8787/mcp or http://127.0.0.1:8787/mcp/ registers and then never matches the resource your server names. A server reached as localhost names a different resource from the same server reached as 127.0.0.1.

Read your app back

To see what a client is registered for, ask for it with its own secret as the credential, as HTTP Basic (on the hosted sandbox, with your developer access token as the lc_dev cookie, as for the delete below):

curl -s "$SANDBOX/v1/sandbox/clients/$CLIENT_ID" -u "$CLIENT_ID:$CLIENT_SECRET" \
  --cookie "lc_dev=$DEVACCESS"
{
  "client_id": "sbx_Zy47k_NDW4E",
  "name": "My server",
  "redirect_uris": ["http://127.0.0.1:4000/callback"],
  "resources": ["http://127.0.0.1:8787/mcp"]
}

The answer never includes the secret, or any record of who registered the client.

Delete your app

When you are done with a client (a test run that registered one, a secret you want to retire), delete it with its own secret as the credential, as HTTP Basic. Whoever holds the secret holds the client: nobody is signed in to a sandbox client, so there is no other owner to ask.

curl -s -X DELETE "$SANDBOX/v1/sandbox/clients/$CLIENT_ID" \
  -u "$CLIENT_ID:$CLIENT_SECRET" --cookie "lc_dev=$DEVACCESS"
{ "deleted": true, "client_id": "sbx_Zy47k_NDW4E" }

Deleting a client removes the resources registered on it. A wrong or missing secret, a credential for a different client, and an unknown client_id all answer 401 alike, so the route says nothing about which ids exist. On the hosted sandbox the Authorization header carries the client's secret, so pass your developer access token as the lc_dev cookie instead (--cookie "lc_dev=$DEVACCESS").

What the deletion ends is the credential: the client can no longer exchange an authorization code, sign in a user or authenticate a server-to-server call, and its redirect URIs leave the allowlist. What stays is the member's: a grant that names the client as grantee and the ledger entries about it are the member's records, and a data-access token already issued against such a grant runs to its expiry (it is bound to the grant, not to the client's secret; revoke the grant to end it early).

2. Mint a test identity (no passkey)

Production sign-in needs a real WebAuthn passkey on a device, which you cannot script. In the sandbox you can mint a synthetic signed-in user instead, so the whole loop runs headlessly (CI, curl, tests):

curl -s -X POST "$SANDBOX/v1/sandbox/test-identity" \
  -H "Authorization: Bearer $DEVACCESS" -H "Content-Type: application/json" -d '{}'
{
  "did": "did:web:sandbox.example:u:817612d13f3219b6",
  "session_token": "lcs_…",
  "expires_at": "2026-06-24T09:00:00+00:00",
  "note": "Synthetic sandbox identity (no passkey)."
}

The session_token is a real user/session token. Use it two ways:

Or create one with a passkey, in a browser

The sandbox also runs the same passkey ceremony as production, on its own pages, for the person's side of the flow: what your user sees when your app sends them to the issuer. Open https://sandbox.lifecare.id/ in a browser (or let /authorize send you there), tick the box for the current member terms and the age confirmation, and create the identity with a passkey. User verification is required, as in production: the device asks for a biometric or a PIN. Sign in again later at https://sandbox.lifecare.id/signin.

Use the passkey path to see and test the person's screens; use the test-identity route above for anything scripted, since an agent or a CI job has no authenticator.

3. Run the whole loop

With a client and a test identity you can exercise everything:

SESSION=lcs_…   # session_token from step 2
DID=did:web:…   # did from step 2

# (a) act as the signed-in user: the session token from step 2 is your credential below
# (b) grant consent for a scope
curl -s -X POST "$SANDBOX/v1/consent/grant" -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" -d '{
  "subject_did":"'"$DID"'","grantee":{"name":"My app","id":"'"$CLIENT_ID"'"},
  "scopes":["cgm"],"purpose":{"text":"demo"},"duration_days":1}'

# (c) the app's data-access token comes from the authorization code flow, not from
# POST /v1/token (see the sentence below); then introspect it as your client
#     steps: sandbox-data-source.md, "4. Get a token"
curl -s -X POST "$SANDBOX/v1/token/introspect" -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" -d '{"token":"lc_…"}'

The hosted sandbox requires the person's session on grant, revoke, grants and ledger exactly as production does, so a loop that works here works there (D-PL4); a well-formed call with no credential is 401 and its detail names the session. An app gets its token from the authorization code flow, as in production: a session is issued a /v1/token token only against the person's own grant (why).

Introspection is the one call here that needs your client credentials, the client_id and client_secret from step 1 (HTTP Basic, as -u sends them). It follows RFC 7662, section 2.1: the endpoint authenticates the resource server that asks, so holding a token string is not enough to read whose data it opens. No credential is 401; a member's session or a holder signature in place of a client credential is 403. Both come before the token is looked up, on the sandbox as in production. See Authorization & tokens § Who may introspect (developer access).

This is the API path, for scripts and CI. An agent takes the authorization code flow, where the person answers a question on the LifeCare.ID® origin: see Sandbox data source, Discovery. Its token carries aud; this one does not.

The sandbox kit (Apache-2.0) runs this end to end: its examples/ register a client and a synthetic person at run time against the hosted sandbox.

A token needs something to open. The sandbox data source honours sandbox tokens and serves synthetic health data: five personas, interpreted outputs only, over REST and over MCP. It introspects every request with its own client credentials, records every read in the ledger, and stops on the call after you revoke. Its page has the walkthrough from registering a client to watching a revoked token fail.


What the sandbox is (and isn't)


Running a source on your machine

The identity server is not distributed: sandbox mode is a runtime flag on the production binary, so no image of it is published, and identity, consent and tokens stay at https://sandbox.lifecare.id. What you can run on your own machine is a data source that checks every token at the hosted sandbox: the kit's local source (compose/; see Run it locally on the sandbox data source page). Register its address as a resource on one of your clients (see Name your own server as a resource).