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.
- Base URL:
https://sandbox.lifecare.id, the hosted sandbox. It is the identity origin for everything here; the identity server is not distributed, so there is nothing to run yourself (see Running a source on your machine). - No operator in the loop: registration and test users are self-service here. Production clients stay operator-provisioned for now (see the roadmap).
- One-time access: the four
/v1/sandbox/*routes below require a developer access token (enter your email + accept the terms, click the magic link); grant, token and ledger calls take the person's session instead, as in production. Two hosts are involved: the token comes from the LifeCare.ID® portal at https://app.lifecare.id/devaccess, and you spend it against the sandbox athttps://sandbox.lifecare.id. The portal's verify page shows the token to use as a Bearer for CLI/CI, and sets thelc_devcookie for the browser. The sandbox host cannot email links itself; its own/devaccesssends you to the portal. - What changes in production: From sandbox to production lists every difference and the steps to promote an app.
- Four endpoints, all sandbox-only (they return
404on a production instance):POST /v1/sandbox/clients,GET /v1/sandbox/clients/{client_id},DELETE /v1/sandbox/clients/{client_id}andPOST /v1/sandbox/test-identity.
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:
- As
Authorization: Bearer lcs_…against the consent panel API (developer access). - As the session cookie to drive the federation (developer access) flow
(
/authorize), exactly as a browser session would. On the hosted sandbox the cookie is named__Host-lc_id_session(the response'snotenames it). The hosted sandbox still accepts the old name for one release.
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.
- The routes are the production ones:
POST /v1/identity/register/beginand/finish(withterms_versionandage_confirmed), thenPOST /v1/identity/auth/beginand/finish. The pages drive them for you. - The relying-party ID is
sandbox.lifecare.id, where production's islifecare.id. A passkey you create here is offered and accepted only on the sandbox; it never appears in the production sign-in, and a production passkey never appears here. - The session cookie is
__Host-lc_id_session, host-only: it goes tosandbox.lifecare.idand nowhere else. - The identity holds synthetic data only, and the pages say so.
- The sandbox does not collect a recovery email: the create page has no recovery field, the sign-in page has no recovery link, and
/recoverand the recovery routes answer404here. Recovery is production's own flow; on the sandbox, if you lose a passkey, make a new identity.
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.
4. Read synthetic data under that consent
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)
- Isolated and synthetic. Separate instance, separate state, zero PHI. Nothing here touches production data or identities. The health data you can read here comes from the sandbox data source, and it is synthetic too.
- Not a passkey bypass for production. The test-identity path exists only on a
sandbox instance; a production instance returns
404for it. The sandbox's own passkeys belong tosandbox.lifecare.idand sign in nowhere else. Production sign-in is always a real passkey, and an app can never act as a user (see Authorization & tokens, developer access). - For building and testing, not for real users or real data. When you are ready for production, you move to operator-provisioned credentials (self-service production registration is on the roadmap).
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).