LifeCare.ID® Developer Docs Public

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.

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:

  1. 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).
  2. Enforces active, token_type: "access", the scope and the resource owner.
  3. Records the access in the owner's ledger (POST /v1/access/record).
  4. 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

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 in scopes_supported, and this issuer answers invalid_scope (one data scope per token). Every 401 from 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.

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):

  1. Send the person to the sandbox's /authorize with response_type=code, your PKCE challenge (S256), one data scope as scope and resource=https://lifecare.id/sandbox-source/mcp (RFC 8707). Optional purpose (up to 200 characters of plain text, shown to the person and written into the grant) and purpose_dpv (a DPV term such as dpv: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).
  2. 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 401 invalid_token inside a token's life stays the person's stop). Nothing is granted until they answer. A no comes back to your redirect URI as error=access_denied.
  3. 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).
  4. POST /token with the code, your code_verifier, your client credentials and resource returns {"access_token":"lc_…","token_type":"Bearer","expires_in":1199,"scope":"<scope>"}. There is no session and no refresh token; with openid also requested, an id_token is added and the access token is still the lc_ one. The answer carries no consent_id: read it from introspection, or from the receipt on your first read.
  5. Send that token to the source. Introspection describes it as token_type access, with the grant's consent_id and the resource as aud. Revoking the grant ends it: the next call is a 401 with 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

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

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.

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:

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.