Sandbox data source ✅
The sandbox gives you identities, grants and tokens. This page is the other half: a data source that honours those tokens, so an app or an agent has something to read under consent. It serves synthetic health data and nothing else.
It is a test fixture. It exists so you can exercise the whole loop (grant, token, read, ledger entry, revoke, refusal) against something that behaves the way a conforming data source (developer access) must, before a real one is involved.
- Base URL:
https://lifecare.id/sandbox-source - Authorization server: the hosted sandbox,
https://sandbox.lifecare.id - What it holds: five synthetic personas. No person, no PHI.
- What it returns: interpreted outputs only. Scores, bands, weekly direction, dates and authored sentences. Never a raw reading.
- Two faces, one set of handlers: REST and MCP.
GET https://lifecare.id/sandbox-source/ describes the source and needs no
token. Its configured field says whether the source has a sandbox to check
tokens against; while it reads false, every data route answers 503.
What the source does on every request
It follows the resource-host contract in Data sources & connectors (developer access), with nothing cached between requests:
- Introspects the bearer token at the sandbox (
POST /v1/token/introspect), presenting the source's own client credentials, as every resource server must (RFC 7662, section 2.1). - Enforces
active,token_type: "access", the scope and the resource owner. - Records the access in the owner's ledger (
POST /v1/access/record). - Serves the persona's data, directly to you.
The record is written before the response, so an access that cannot be written
to the ledger is not served. Because step 1 runs on every request, a revoked
grant stops the very next call. What the source sends to LifeCare.ID® is
{subject_did, scope, purpose, accessor, consent_id} and never a value; the
consent_id is the one introspection returned for the token, so the ledger
entry names the grant the read was made under (left out when introspection
returned none).
Walkthrough
Everything below is copy and paste. On the hosted sandbox the two self-service calls need your developer access token (see Sandbox).
SANDBOX=https://sandbox.lifecare.id
SOURCE=https://lifecare.id/sandbox-source
DEVACCESS=… # the token from https://app.lifecare.id/devaccess (the portal's verify page)
1. Register a sandbox client
curl -s -X POST "$SANDBOX/v1/sandbox/clients" \
-H "Authorization: Bearer $DEVACCESS" -H "Content-Type: application/json" \
-d '{"name":"Pilot agent","redirect_uris":["http://127.0.0.1:4000/callback","http://localhost:4000/callback"]}'
CLIENT_ID=sbx_… # client_id from the response
CLIENT_SECRET=… # client_secret from the response, shown once
The redirect URI your client sends to /authorize must be one of these, byte for
byte: localhost and 127.0.0.1 are different strings, and anything else is a
400 page, not a redirect. The samples below use http://127.0.0.1:4000/callback.
2. Mint a synthetic identity
curl -s -X POST "$SANDBOX/v1/sandbox/test-identity" \
-H "Authorization: Bearer $DEVACCESS" -H "Content-Type: application/json" -d '{}'
DID=did:web:sandbox.lifecare.id:u:… # did from the response
SESSION=lcs_… # session_token from the response
3. Grant a scope
The synthetic person grants your client the recovery scope. The
call carries the person's own session, which is the credential a person acts
with.
curl -s -X POST "$SANDBOX/v1/consent/grant" \
-H "Authorization: Bearer $SESSION" -H "Content-Type: application/json" -d '{
"subject_did":"'"$DID"'",
"grantee":{"name":"Pilot agent","id":"'"$CLIENT_ID"'"},
"scopes":["recovery"],
"purpose":{"text":"agent governance pilot"},
"duration_days":1}'
CONSENT_ID=urn:lifecare:consent:… # consent_id from the response
A grant made through this API may name several scopes. A token is always one scope (step 4), and the authorization code flow under Discovery asks for one scope per grant. The flow reuses an identical active grant (one scope, the same purpose), so with the purpose below step 4 makes no second grant and step 7 revokes the grant the token was issued under.
4. Get a token
An app gets its token from the authorization code flow, in the sandbox exactly as
in production (D-PL4). POST /v1/token is not the app's route: a session is
issued a token from it only against the person's own grant. Tokens are single
scope and short lived; expires_in in the response says how long.
On the sandbox the synthetic person's yes is given headless (see Saying yes in the sandbox), then the code is exchanged with PKCE and your client credentials:
VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
REDIRECT=http://127.0.0.1:4000/callback
RESOURCE=https://lifecare.id/sandbox-source/mcp
COOKIE="__Host-lc_id_session=$SESSION"
# the grant question, then the yes: post the page's hidden fields with decision=approve
PAGE=$(curl -s -b "$COOKIE" "$SANDBOX/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=$REDIRECT&state=s1&code_challenge=$CHALLENGE&code_challenge_method=S256&scope=recovery&purpose=agent%20governance%20pilot&resource=$RESOURCE")
ARGS=(); while read -r k v; do ARGS+=(--data-urlencode "$k=$v"); done < <(printf %s "$PAGE" | grep -o '<input type="hidden" name="[a-z_]*" value="[^"]*">' | sed 's/.*name="\([a-z_]*\)" value="\([^"]*\)">/\1 \2/')
CODE=$(curl -s -o /dev/null -D - -b "$COOKIE" "${ARGS[@]}" -d decision=approve "$SANDBOX/data-consent/decide" | sed -n 's/^[Ll]ocation: .*[?&]code=\([^&[:space:]]*\).*/\1/p')
curl -s -X POST "$SANDBOX/token" -d grant_type=authorization_code -d "code=$CODE" \
-d "redirect_uri=$REDIRECT" -d "code_verifier=$VERIFIER" -d "resource=$RESOURCE" \
-d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_SECRET"
TOKEN=lc_… # access_token from the response
5. Read synthetic data over REST
curl -s "$SOURCE/v1/source/recovery?owner=$DID" -H "Authorization: Bearer $TOKEN"
{
"fixture": true,
"notice": "Synthetic persona data from the LifeCare.ID® sandbox reference source. Not a person. Zero PHI. Test fixture.",
"resource_owner": "did:web:sandbox.lifecare.id:u:817612d13f3219b6",
"scope": "recovery",
"purpose": "agent governance pilot",
"requester": "sbx_Zy47k_NDW4E",
"consent_id": "urn:lifecare:consent:8e1f…",
"persona": { "persona_id": "p3-under-recovered", "display_name": "Under-Recovered Athlete", "selected_by": "did-hash" },
"as_of": "2026-10-01",
"access_recorded": true,
"ledger_entry_hash": "43bcec11…",
"data": {
"covered": true,
"pillar": "recovery",
"score": 0.0,
"band": "off-track",
"as_of": "2026-10-01",
"weekly": [
{ "week_index": 0, "first_day": "2026-09-02", "last_day": "2026-09-08",
"covered": true, "score": 51.0, "band": "drifting", "as_of": "2026-09-08", "direction": "first-reading" }
],
"sentence": "Recovery is off track: sleep is short and overnight recovery sits well below this persona's own baseline.",
"sleep_label": "under-rested"
}
}
The read is now in the person's ledger, attributed to
sandbox-source:synthetic-personas, and its payload carries the consent_id
the token was issued under, so the entry links back to the grant from step 3:
curl -s "$SANDBOX/v1/consent/ledger/$DID" -H "Authorization: Bearer $SESSION"
{ "event_type": "data_access",
"description": "sandbox-source:synthetic-personas read your recovery data. Purpose: agent governance pilot.",
"payload": { "scope": "recovery", "purpose": "agent governance pilot",
"accessor": "sandbox-source:synthetic-personas",
"consent_id": "urn:lifecare:consent:8e1f…" } }
6. Connect an MCP client
The MCP endpoint is https://lifecare.id/sandbox-source/mcp (streamable HTTP).
The bearer token on the transport is the same sandbox access token. Any MCP
client that can send a header will connect; for example:
{
"mcpServers": {
"lifecare-sandbox-source": {
"type": "http",
"url": "https://lifecare.id/sandbox-source/mcp",
"headers": { "Authorization": "Bearer lc_…" }
}
}
}
A client that follows the MCP authorization specification needs no header: it
starts from the 401 and asks the person, as described under
Discovery, with a ready-to-run client.
Or by hand:
curl -s -X POST "$SOURCE/mcp" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"read_scope","arguments":{"scope":"recovery","owner":"'"$DID"'"}}}'
The tool result carries the same document as step 5, as structuredContent and
as JSON text.
7. Revoke, and see the next call fail
curl -s -X POST "$SANDBOX/v1/consent/revoke" \
-H "Authorization: Bearer $SESSION" -H "Content-Type: application/json" \
-d '{"consent_id":"'"$CONSENT_ID"'"}'
curl -s -i "$SOURCE/v1/source/recovery?owner=$DID" -H "Authorization: Bearer $TOKEN"
HTTP/2 401
www-authenticate: Bearer error="invalid_token", scope="recovery"
{"detail":"token inactive or unknown","error":"invalid_token"}
The MCP endpoint refuses the same token with the same 401 body, on every
method. Its WWW-Authenticate challenge also carries resource_metadata, the
address of its protected resource metadata (see Discovery), and the
one scope it suggests (daily, or the scope a single read_scope call names).
REST reference
All data routes take Authorization: Bearer <sandbox access token> and answer
Cache-Control: no-store.
| Route | Token scope | Returns |
|---|---|---|
GET /sandbox-source/ |
none | the source's description; configured says whether it has a sandbox to check tokens against, client_credentials whether it presents its own client credentials there (introspection needs them) |
GET /sandbox-source/v1/scopes |
any | the scope vocabulary, the one scope this token reads, the owner and the persona. Records nothing |
GET /sandbox-source/v1/source/{scope}?owner={did} |
{scope} |
that scope for the token's owner |
GET /sandbox-source/v1/weekly-summary?owner={did}&week={n} |
daily |
one week across every pillar, plus the persona's headline. week is optional and defaults to the latest |
owner is required on every read and must be the DID the token was issued for.
That is the subject check a data source owes the person, and it is never skipped.
Scopes
The source follows the scope vocabulary (developer access). Each payload
carries covered and a sentence; a scope a persona has no data for says so
instead of inventing a reading.
| Scope | What comes back |
|---|---|
recovery |
the recovery band and score, weekly direction, a sleep label |
activity |
the muscle stimulus band and score from training, weekly direction, the training modality, a movement band |
cgm |
the glucose stability band and score, weekly direction, an anomaly flag. Covered for one persona only |
body_composition |
a muscle retention band and the direction of weight and lean mass. No mass, no percentage |
daily |
every pillar's current band, coverage day by day, the focus, the challenge week |
insights |
the newest derived insight per family, each a categorical label |
labs |
covered: false. No persona has laboratory results |
told_to_guardian is not served: it is what a person tells their guardian, held
by their node, and no data source holds it. A read of it answers 404
unknown_scope.
Bands are on-track, drifting and off-track; retention bands are
excellent, good and watch; directions are improving, steady,
declining and first-reading. Scores run from 0 to 100 and are derived, in the
same sense as the node's own contract: no response field holds a reading, a
mass, a percentage or a count of anything measured, and no sentence holds a
digit.
Errors
Every refusal is {"detail": "...", "error": "<code>"}. Every 401
carries WWW-Authenticate: Bearer, with error="invalid_token" when a token was
presented, and always scope, the one scope the source suggests: the scope the
request was for when it names one (a REST read of a scope, or a single
tools/call on read_scope), otherwise daily. On the MCP path the challenge
also carries resource_metadata (see Discovery). A 403 insufficient_scope on the REST face carries
WWW-Authenticate: Bearer error="insufficient_scope", scope="<the scope the read
asked for>". On the MCP face a single tools/call for another scope is refused
at the transport in the same way: HTTP 403, the same {detail, error} body,
and the same header with resource_metadata added, so a client that follows the
MCP authorization specification can step up (see Stepping up to another
scope). Only insufficient_scope is answered
that way. A call refused for its owner (wrong_subject), for a scope outside the
vocabulary (unknown_scope), or for a missing owner (owner_required) is
answered inside the tool result (isError: true, the same body, status as in the
table). A JSON-RPC batch keeps that tool-result shape for every refusal,
insufficient_scope included, because one HTTP status cannot speak for several
requests. Nothing is written to the owner's ledger for a refused call.
| Status | error |
When |
|---|---|---|
401 |
missing_token |
no bearer token |
401 |
invalid_token |
the sandbox says the token is not active: unknown, expired, or its grant was revoked |
401 |
invalid_token |
the token was issued for another resource (its audience is not https://lifecare.id/sandbox-source/mcp). Nothing is read or recorded |
403 |
wrong_token_type |
a session token, or any token that is not a data-access token |
403 |
insufficient_scope |
the token covers a different scope. The WWW-Authenticate header names the scope the read asked for, so you know which to ask for. On the MCP face this is an HTTP 403 for a single tools/call, and a tool error inside a batch |
403 |
wrong_subject |
owner is not the DID the token was issued for |
400 |
owner_required |
no owner named |
404 |
unknown_scope |
the scope is not in the vocabulary |
404 |
unknown_week |
the persona has no such week |
503 |
introspection_unavailable |
the sandbox could not be asked about the token. Nothing is served |
503 |
source_not_authorized |
the sandbox refused the source's own client credentials (missing or wrong), so it could not check the token. Your token was not looked up. Nothing is served |
503 |
access_record_failed |
the access could not be written to the ledger. Nothing is served |
503 |
source_not_configured |
the source has no sandbox to check against |
MCP reference
POST https://lifecare.id/sandbox-source/mcp: streamable HTTP, stateless, JSON
responses. There is no session and no server-initiated stream, so GET answers
405.
A test fixture for agent governance pilots. This is not the member MCP surface, and its tools are not a preview of one. It exists so a gateway, a firewall or a policy layer in front of an agent has a consent-bound health data server to be tested against.
| Tool | Arguments | Token scope |
|---|---|---|
list_scopes |
none | any |
read_scope |
scope, owner |
scope |
get_weekly_summary |
owner, optional week |
daily |
- Every message is authorized.
initializeandtools/listincluded: a missing, inactive or wrong-type token is refused at the HTTP layer with the401and403shapes above, so a revoked grant ends the session at the next message. - A wrong-scope call is refused at the transport. A single
tools/callwhose token covers another scope is answered HTTP403with{detail, error}as the body andWWW-Authenticate: Bearer error="insufficient_scope", scope="<the scope the call asked for>", resource_metadata="<the metadata address>". A client that follows the MCP authorization specification re-runs authorization for the scope named, which sends the person back for a second grant, and retries once with the new token. Nothing is recorded for the refused call. - Owner and unknown-scope refusals are tool errors.
wrong_subject,unknown_scopeandowner_requiredare not something the person can be asked to widen. The result hasisError: trueandstructuredContentof{detail, error, status}with the same codes as REST. - A batch keeps the tool-error shape. Inside a JSON-RPC batch a wrong-scope
call is a tool error for that element too (
isError: true, status403, no header): one HTTP status cannot speak for several requests. Send atools/callon its own to receive the step-up challenge. - Tokens are single scope. A stock MCP SDK holds one token per connection:
stepping up replaces it, and going back to the first scope asks the person again
(the grant is reused, but the question is still asked). An agent that alternates
between scopes keeps one connection per scope.
list_scopesnames the owner and the readable scope, which is the natural first call. - You get the token from the sandbox, as in the walkthrough or through the authorization code flow described under Discovery, and send it as a header. The endpoint does not issue tokens and has no sign-in page of its own; what it publishes is where to find the sandbox, as described next.
Discovery
This is person-managed authorization: the person, not the agent or the server, decides what an agent may read, through the flow that MCP's authorization specification describes. LifeCare.ID® is its first implementation, and Person-managed authorization is the library for both halves.
A client that follows the MCP authorization specification does not need to be
told where the sandbox is. The endpoint answers a request without a valid
token with 401 and a WWW-Authenticate header that carries
resource_metadata, the address of its OAuth 2.0 Protected Resource Metadata
(RFC 9728), and scope, one suggested
scope (daily, the broadest everyday scope; it may change with the profile
draft). Ask for that one, or for the one data scope you need. A stock MCP SDK
uses the suggestion when you configure no scope. Never ask for more than one:
HTTP/2 401
www-authenticate: Bearer resource_metadata="https://lifecare.id/.well-known/oauth-protected-resource/sandbox-source/mcp", scope="daily"
A token that was presented and refused (expired, revoked, for another resource,
or without an audience) gets error="invalid_token" and the same scope. A
single tools/call for a scope names that scope instead of daily. Every 401
names the one scope, so a stock client that reconnects after expiry or
revocation asks for that scope and recovers on its own. The metadata document
lives at:
https://lifecare.id/.well-known/oauth-protected-resource/sandbox-source/mcp
It names the resource (https://lifecare.id/sandbox-source/mcp), the one
authorization server (https://sandbox.lifecare.id), the scopes the source
accepts, and that the token travels in the Authorization header. From there a
client reads the sandbox's metadata for its authorization and token endpoints.
The sandbox publishes both forms, the same document at each: RFC 8414 at
https://sandbox.lifecare.id/.well-known/oauth-authorization-server, which an
MCP client tries first, and OpenID configuration at
https://sandbox.lifecare.id/.well-known/openid-configuration. Its
scopes_supported lists openid, email and the seven data scopes, the same
seven the source's metadata lists.
The source accepts only a token issued for its own resource, the MCP endpoint
named as resource above, on both the REST and the MCP face, and says so with
401 invalid_token when the token names another. That address follows the
origin the source runs on, so a token issued for the hosted source is refused by a
copy of the source run elsewhere, such as the compose server in Run it
locally. To read from your own copy, register its address as a
resource on one of your clients, exactly as the copy names itself (for the compose
server, http://localhost:8799/sandbox-source/mcp; see Name your own server as a
resource), and ask for that
resource. Walked on 2026-11-04: a token issued for that address was read by the
compose source on localhost:8799. The kit's copy of the source trails the hosted
source (0.3.1) until its next sync; the hosted source has everything described
here.
The hosted source checks no grantee: it accepts a token issued to any client. A
server of your own should decide by grantee (requester on introspection); see
Data sources & connectors (developer access). A token with no
audience, from POST /v1/token (a person's own script on their own grant), is
refused by the hosted source with 401 ("this source requires a token with an
audience; take your token through the code flow"), because the sandbox accepts a
ledger line only under a token the source served and such a read could not be
recorded.
Status: live on the hosted sandbox since 2026-11-03. The path described below runs at
https://sandbox.lifecare.id; the production issuer does not have it. Source 0.3.2. The official MCP TypeScript SDK (1.32.2) completed the whole loop against it: discovery, the grant question, the token, one read with its consent id, revoke, the refused read, and a second authorization that the sandbox recognised as the first. One note for stock clients. When a challenge names no scope, the SDK asks for every scope inscopes_supported, and this issuer answersinvalid_scope(one data scope per token). Every401from this source sends one scope in its challenge, the first and the one after an expired or revoked token alike; a stock client that takes the challenge's scope asks for that one. To read another scope, set it in the sample below, or let the step-up ask the person for it.
Connect a stock MCP client
This sample uses a client registered at the sandbox (step 1):
confidential, with client_secret_post or client_secret_basic, and a redirect
URI registered byte for byte. The sandbox does not advertise dynamic client
registration, so the provider below has no saveClientInformation. It asks for
exactly one scope. Connect first and let the 401 lead: calling the SDK's auth()
directly skips the challenge and asks for all seven scopes, which this issuer
refuses. list_scopes names the owner as token.resource_owner.
// agent.mjs: a stock MCP client reading the sandbox source under a person's yes.
// Node 22 or later; npm install @modelcontextprotocol/[email protected]
import http from "node:http";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
const RESOURCE = new URL("https://lifecare.id/sandbox-source/mcp");
const REDIRECT = "http://127.0.0.1:4000/callback"; // one of the client's redirect URIs, byte for byte
const SCOPE = "daily"; // exactly one data scope: tokens are single scope
const { CLIENT_ID, CLIENT_SECRET } = process.env; // the client you registered
let held, verifier, authorizeUrl;
const provider = {
get redirectUrl() { return REDIRECT; },
get clientMetadata() {
return { client_name: "Pilot agent", redirect_uris: [REDIRECT], grant_types: ["authorization_code"],
response_types: ["code"], token_endpoint_auth_method: "client_secret_post" };
},
clientInformation() { return { client_id: CLIENT_ID, client_secret: CLIENT_SECRET }; }, // no saveClientInformation: no dynamic registration
state() { return crypto.randomUUID(); },
tokens() { return held; },
saveTokens(tokens) { held = tokens; },
redirectToAuthorization(url) { // the SDK hands you the URL; it does not open it
const asked = url.searchParams.get("scope");
if (!asked || asked.includes(" ")) url.searchParams.set("scope", SCOPE); // the source's challenge names one scope; this only guards a source that names none
authorizeUrl = url;
},
saveCodeVerifier(v) { verifier = v; },
codeVerifier() { return verifier; },
};
// Your redirect URI is yours to serve: read the code, check state and issuer.
function waitForCallback(state) {
return new Promise((resolve, reject) => {
const server = http.createServer((req, res) => {
const p = new URL(req.url, "http://127.0.0.1:4000").searchParams;
res.writeHead(200, { "content-type": "text/plain", connection: "close" }); // not keep-alive: the next listener reuses port 4000
res.end("You can close this tab.");
server.close();
if (p.get("error")) return reject(new Error(p.get("error"))); // a no is error=access_denied
if (p.get("state") !== state || p.get("iss") !== "https://sandbox.lifecare.id") {
return reject(new Error("state or issuer mismatch"));
}
resolve(p.get("code"));
}).listen(4000, "127.0.0.1");
});
}
const newTransport = () => new StreamableHTTPClientTransport(RESOURCE, { authProvider: provider });
async function connect() {
const client = new Client({ name: "pilot-agent", version: "0.1.0" });
await client.connect(newTransport()); // the first request meets the 401; the SDK reads it and runs discovery
return client;
}
// Show the person authorizeUrl, wait for the redirect, and exchange the code.
async function askPerson() {
const pending = waitForCallback(authorizeUrl.searchParams.get("state")); // listen before the person is asked
console.log("Ask the person to open:", authorizeUrl.href);
await newTransport().finishAuth(await pending); // exchanges the code at /token
}
// Connect; when the SDK stops at the redirect, ask the person and try again.
async function connected() {
try {
return await connect();
} catch (e) {
if (!(e instanceof UnauthorizedError)) throw e;
await askPerson();
return await connect();
}
}
const client = await connected();
const scopes = await client.callTool({ name: "list_scopes", arguments: {} });
const owner = scopes.structuredContent.token.resource_owner;
const read = await client.callTool({ name: "read_scope", arguments: { scope: SCOPE, owner } });
console.log("read", SCOPE + ":", read.structuredContent.consent_id, "recorded:", read.structuredContent.access_recorded);
await client.close();
Run with CLIENT_ID and CLIENT_SECRET from step 1:
npm install @modelcontextprotocol/[email protected]
CLIENT_ID=sbx_… CLIENT_SECRET=… node agent.mjs
It prints a line, "Ask the person to open", and waits. The person's yes is
described next. Walked on 2026-11-04 against the hosted sandbox, it ends with a
line of the form read daily: urn:lifecare:consent:… recorded: true.
Saying yes in the sandbox
In production the person answers on their own device with their passkey. A
sandbox identity has no passkey: its session_token (step 2) stands in for the
sign-in. A passkey sign-in on the sandbox origin has not been walked. The
session lasts a day. There are two ways to give the yes, both walked on
2026-11-04.
- In a browser, to see what the person sees. Open
https://sandbox.lifecare.id/in a browser, open the developer console on that page, and set the session cookie:document.cookie = "__Host-lc_id_session=lcs_…; Path=/; Secure; SameSite=Lax". Then open the authorize URL the agent printed, in the same tab. The grant question appears; Allow sends the browser to your redirect URI, where your receiver answers "You can close this tab". This is the one step of the flow a developer does by hand in a browser. - Headless, for scripts and CI. Fetch the authorize URL with the cookie
__Host-lc_id_session=<session_token>, read the hidden fields of the form in the page, and post them withdecision=approvetohttps://sandbox.lifecare.id/data-consent/decidewith the same cookie. The answer is a303to your redirect URI withcode,stateandiss. The form's markup is not a contract; the kit's examples do this and are kept in step with it.
The sandbox runs with LIFECAREID_REQUIRE_GRANT_PROOF off today. When it turns
the setting on, a yes to a client outside the first party will count only after
the person confirms it with their passkey on the page, and both ways above will
then need a person with a passkey, created on the sandbox's create page: a
synthetic test identity has none, so its yes will be refused with
access_denied. What the page does and what your client sees then is in
The person confirms the yes with their passkey.
The five steps, by hand
With a client registered at the sandbox (step 1):
- Send the person to the sandbox's
/authorizewithresponse_type=code, your PKCE challenge (S256), one data scope asscopeandresource=https://lifecare.id/sandbox-source/mcp(RFC 8707). Optionalpurpose(up to 200 characters of plain text, shown to the person and written into the grant) andpurpose_dpv(a DPV term such asdpv:Service). Without a purpose the grant records "Data access by" and your client's name (cut if needed so the whole purpose stays within 200 characters). - The person is asked the grant question on the LifeCare.ID® origin: who asks,
what the scope covers in plain words, the purpose, the resource, and until when
(30 days at most; the person will be able to choose a shorter term once the
sandbox turns consent narrowing on, so your client never assumes 30 days; it asks
the person again when a token reaches its own end or a code is refused with
invalid_grant, and a 401invalid_tokeninside a token's life stays the person's stop). Nothing is granted until they answer. A no comes back to your redirect URI aserror=access_denied. - A yes makes a grant with your client as the grantee: one scope, up to 30 days (shorter once consent narrowing arrives and the person chooses so), the purpose shown. It returns a code to your redirect URI. The API path in step 3 of the walkthrough can name several scopes and its own duration. An identical active grant made either way is reused (see below).
POST /tokenwith the code, yourcode_verifier, your client credentials andresourcereturns{"access_token":"lc_…","token_type":"Bearer","expires_in":1199,"scope":"<scope>"}. There is no session and no refresh token; withopenidalso requested, anid_tokenis added and the access token is still thelc_one. The answer carries noconsent_id: read it from introspection, or from the receipt on your first read.- Send that token to the source. Introspection describes it as
token_typeaccess, with the grant'sconsent_idand the resource asaud. Revoking the grant ends it: the next call is a401with the challenge.
The authorize URL, with every parameter, and the token request as curl (PKCE
as openssl writes it; the person's yes as under "Saying yes" above):
VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)
echo "$SANDBOX/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=http%3A%2F%2F127.0.0.1%3A4000%2Fcallback&state=$STATE&code_challenge=$CHALLENGE&code_challenge_method=S256&scope=daily&resource=https%3A%2F%2Flifecare.id%2Fsandbox-source%2Fmcp"
# the person answers; the redirect carries code, state and iss
curl -s -X POST "$SANDBOX/token" \
-d grant_type=authorization_code -d "code=$CODE" \
-d "redirect_uri=http://127.0.0.1:4000/callback" -d "code_verifier=$VERIFIER" \
-d "resource=https://lifecare.id/sandbox-source/mcp" \
-d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_SECRET"
Authenticate at /token with client_secret_post (as above) or
client_secret_basic. A client identified by a metadata document holds no shared secret: it
authenticates with none or private_key_jwt, as its document declares
(Client-ID metadata documents). The sandbox's metadata
also lists refresh_token, which applies to native sign-in only, never to a data scope. The
metadata advertises no introspection_endpoint; a resource server introspects at
/v1/token/introspect.
Your redirect URI is yours to serve. A small listener on 127.0.0.1:4000 reads
code, state and iss, checks that state is the one you sent and iss is
https://sandbox.lifecare.id, and hands the code to finishAuth or to the
curl above. The receiver in the sample does that. It answers with
Connection: close on purpose: a keep-alive connection from a browser or an HTTP
client would carry the next callback to the listener that has already closed.
Every authorization response from the sandbox carries iss, the issuer
(RFC 9207), and the metadata says so
(authorization_response_iss_parameter_supported). Each rendering of the grant
question can be answered once. Refusals come back to your redirect URI as an
error redirect, with your state and iss:
error |
When |
|---|---|
invalid_scope |
more than one data scope, an unknown scope, or email together with a data scope |
invalid_target |
no resource, more than one, or one this issuer does not serve: not the sandbox source, and not a resource registered on a client of yours (see Name your own server as a resource). A resource registered by another developer, one on a client registered before 2026-11-04, or a spelling that differs by one byte is refused the same way |
invalid_request |
a purpose over 200 characters or with control characters, or a malformed purpose_dpv |
unauthorized_client |
one of the operator-listed native public clients. A data-access token goes to a registered client with a secret, or to a client identified by a client-ID metadata document |
access_denied |
the person said no, or the question waited too long |
Steps 3 and 4 of the walkthrough stay as the API path, for scripts and CI that
have no browser and no person. A real agent takes the authorization code flow.
Both give a single-scope lc_ token under a grant, but only the authorization
code token carries aud: a walkthrough token has none, and a server that
requires an audience refuses it.
A generic client either has a client registered at the sandbox
(step 1), which authenticates with a secret at
/token, or identifies itself by a client-ID metadata document, with no
registration and no secret (Client-ID metadata documents).
The sandbox's configuration does not advertise dynamic client registration.
Only the path form above answers. The address without the path
(/.well-known/oauth-protected-resource) is a 404, because the resource is
the MCP endpoint and not the whole site. The REST face keeps a plain Bearer
challenge.
Asking again: reuse, expiry and revoke
- Reuse. If the person already holds an identical grant (same client, scope,
purpose text and DPV term, not revoked, not expired), the page adds "You already
allow this until
. Allowing again does not add a second grant." The Until line shows that grant's own date, and a yes adds a consent_reaffirmedentry to the person's ledger instead of a new grant. Keep yourpurposeconstant, or omit it, so reuse can match. The person is still asked every time. - Expiry. On the hosted sandbox a data token lives 1200 seconds
(
expires_in1199 when issued) and comes with no refresh token. When it ends, the source answers401 invalid_tokenwith the challenge. A stock SDK throwsUnauthorizedErrorat the request and stops at the redirect; run the same block again, and the person sees the reuse sentence and answers again. The sample does this inconnected(). - Revoke. Revoking is the person's: the data-rights panel, or in the sandbox
POST /v1/panel/revokeorPOST /v1/consent/revokewith the synthetic person's session. Revoking a grant ends every token issued under it, from every authorization that reused it. The agent finds out at its next request: a401that arrives within the token's life is the person's stop, so drop the token and do not ask again by yourself unless a person wants it. The issuer'srevocation_endpoint(/revoke) is for native apps' sign-in refresh tokens: it answers200to a data token and revokes nothing (walked on 2026-11-04).
From a browser
A page on another origin can read the challenge: the source exposes
WWW-Authenticate over CORS on every 401 and on a 403 insufficient_scope,
and exposes Mcp-Session-Id and MCP-Protocol-Version too. A page can also
fetch the source's metadata and call the source with a token (the Authorization
header is allowed). The sandbox issuer answers a page on another origin on five
routes: the RFC 8414 document (/.well-known/oauth-authorization-server), the
OpenID configuration, the JWKS, /token and /revoke. Each sends
Access-Control-Allow-Origin: * and exposes WWW-Authenticate, on errors as well
as successes, and answers an OPTIONS preflight with 204. Nothing else sends
CORS headers: not /authorize (a redirect your page navigates to), not
/v1/sandbox/*, not introspection. Status: sandbox only. Production sends no
CORS headers on its issuer, and waits for a ruling before any change. So a page can
discover and read the issuer's documents and errors at the sandbox; a registered
sandbox client is confidential, so its code exchange belongs on a backend that holds
the client secret; a client identified by a
client-ID metadata document holds no shared secret.
The pattern that also works in production: the page sends the person to /authorize (a
top-level navigation works), a backend you run receives the redirect and
exchanges the code with the client secret, and the page then carries the token to
the source. The backend is the receiver and the curl above, in your language.
Stepping up to another scope
Tokens are single scope. A stock MCP SDK holds one token per connection: stepping up replaces it, and going back to the first scope asks the person again (the grant is reused, but the question is still asked). An agent that alternates between scopes keeps one connection per scope.
A client holding a daily token that asks read_scope for cgm receives the
403 described under Errors and the MCP notes, naming cgm. On REST
the same refusal is:
HTTP/2 403
www-authenticate: Bearer error="insufficient_scope", scope="cgm"
(the scope in the header is the one the read asked for). A client that follows
the specification starts a new authorization for that scope, the person answers a
second grant question, and the call is retried with the second token. A REST
client re-runs the authorization code flow for the scope named itself. With the
sample above, the SDK throws UnauthorizedError on the refused call, with
authorizeUrl set for cgm; call askPerson(), connect again and repeat the
call. The person's panel then shows two grants, one per scope, which is correct.
This issuer refuses a request for two scopes (invalid_scope), so a client that
asks for the union of the scope it holds and the scope named, as the
specification suggests, is refused. Ask for the one scope named. The
authorization profile will settle the union question.
The personas
Five synthetic members, thirty days each, generated by the challenge readiness simulation that the node is tested against. Each is built to show one thing.
| Persona | What it shows |
|---|---|
p1-adherent-responder |
the healthy case: weight comes down while lean mass holds |
p2-glp1-muscle-loser |
weight comes down fast, a meaningful share of it lean, with exercise that is all cardio |
p3-under-recovered |
frequent training on short sleep: training on track, recovery off track |
p4-sparse-returner |
data that arrives, stops for a long stretch and resumes |
p5-glucose-anomaly |
glucose stability falling through the month while everything else stays flat |
Which persona you get. The source maps the resource owner's DID onto a persona: SHA-256 of the DID, the first four bytes read as a big-endian unsigned integer, modulo five, indexing the list above in order. The same identity always reads the same persona.
Choosing one. A grant whose purpose text carries persona:<id> pins that
persona, for example "purpose":{"text":"agent governance pilot persona:p2-glp1-muscle-loser"}
(and the same text as purpose on the token request). The pin lives in the
purpose the synthetic person consented to, so it cannot be changed per request.
The response's persona.selected_by says which rule applied: did-hash or
purpose.
The window is fixed. The data covers the thirty days ending on as_of. It
does not move with the calendar, and nothing new arrives.
Limits you should know about
- It is only as available as the sandbox. The source runs on the edge, but
it checks every token at the hosted sandbox. While the sandbox is unreachable
the source answers
503 introspection_unavailableand serves nothing. - Rate limits are the sandbox's. The sandbox does not rate-limit today;
production does. Every caller of this source arrives at the sandbox from the
same place, so if a limit is ever switched on there, a burst from one tester
could produce
503for another. - The reader is named by a label. The ledger entry names the source as
sandbox-source:synthetic-personas. A production source should have its own DID and recordactor_did(see Node identity, developer access). - It is not a conformance suite. It shows the behaviour a source owes; it does not certify yours. See the roadmap.
Consent-ops stub
Beside the source sits a small fixture for one job: letting an assistant list the
four tools of the planned consent-ops server and choose among them from their
descriptions alone. It is https://lifecare.id/sandbox-consent-ops-stub/mcp, the
same streamable HTTP transport as the source, and it is for tool-selection tests
only. Every tool call returns a fixed placeholder that says it is a stub: no
identity, no grant, no ledger entry, no network call, nothing stored.
- The tools.
request_grant,ledger_recent,registry_viewandrevoke, with the descriptions and annotations of the consent-ops design. When the consent-ops server is built, the same descriptions carry over, and a change to one is retested against this stub first. - No sign-in. The stub serves only public tool definitions and fixed text, so
it publishes no protected resource metadata and never answers
401. A client that lists tools connects without a token. It reads no input beyond the method and tool name, accepts bodies up to 16 kilobytes, and sendsX-Robots-Tag: noindex. - Try it. In an MCP client that takes a URL (in Claude, a custom connector), add that address and list the tools. For a quick look by hand:
curl -s https://lifecare.id/sandbox-consent-ops-stub/mcp \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
What the stub adds beyond the four ruled definitions, for whoever runs the selection test:
- Input schema of
request_grant: one optionalcategorystring. - Input schema of the other three tools: no arguments.
- Server name:
lifecare-consent-ops-stub. - Server title: "LifeCare.ID® consent operations (sandbox stub)".
- No
instructionsin the initialize result, and no tool titles.
What comes next is the consent-ops server itself, which replaces the placeholders with the person's real grant and ledger; the stub stays as the selection fixture.
Run it locally
The source, its tests, a Compose file that runs it on your machine and an
example client that runs the whole loop are the public sandbox kit,
github.com/enbarca/lifecareid-sandbox
(Apache-2.0). The source you run checks every token at the hosted sandbox, as
the hosted source does, with a client of its own: register one with your
developer access token (step 1 of the sandbox guide) and put its
id and secret in compose/.env. There is no identity server to run: 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.
git clone https://github.com/enbarca/lifecareid-sandbox && cd lifecareid-sandbox/compose
cp .env.example .env # SOURCE_CLIENT_ID and SOURCE_CLIENT_SECRET: the client you registered
docker compose up
# SOURCE=http://localhost:8799/sandbox-source (SANDBOX stays https://sandbox.lifecare.id)
The walkthrough above then runs unchanged with SOURCE pointed at your
machine, developer access token included; the kit's compose/README.md has it
by hand, and examples/run-loop.mjs runs every step and checks each answer
(LIFECAREID_DEVACCESS_TOKEN=... SOURCE=http://localhost:8799/sandbox-source node examples/run-loop.mjs).
The hosted source itself is a Cloudflare Pages Function; the kit's pages/
folder is that deployment, with the two project variables it reads.