LifeCare.ID® Developer Docs Public

Person-managed authorization

Person-managed authorization lets a person decide what an agent may read from a server, and stop it at any time, using the OAuth flow that MCP already follows. LifeCare.ID® is its first implementation.

This page covers the library for both halves: the agent that asks, and the server that holds something of a person's.

Status: draft 1. The flow below is live on the hosted sandbox and the library follows it as it behaves on 2026-11-04. The library is built and not yet published: it lives in the sandbox kit under lib/person-managed-auth/, and you import it by relative path from a clone (see Use it from your own project); the package name is confirmed at publication. The profile is a written specification of this flow that other implementations can follow; it is planned for 2026-12-01, and the shapes may change when it is published (each is marked profile draft 1 may change this in the code). Nothing here is a claim that a production server or a data holder honours the grant yet.


How it works

  1. The agent asks the server for a read with no token. The server answers 401 with resource_metadata and the one scope it suggests.
  2. The agent reads the server's metadata, which names the authorization server, and then that server's own metadata.
  3. The agent sends the person to the authorization server's authorize URL: one scope, PKCE, and the resource the token is for.
  4. The person answers on the authorization server's own origin, on their own device. A yes returns a code to the agent.
  5. The agent exchanges the code for a token bound to that scope, that client and that resource.
  6. The agent reads with the token. For every request the server asks the authorization server whether the token is still active, writes one line to the person's ledger, and answers with a receipt.
  7. The person revokes. The server's very next request finds the token inactive and refuses it, and the agent stops.

What holds throughout:

For an agent

You need a client registered at the authorization server. On the hosted sandbox, register one with your developer access token (Sandbox, step 1), with http://127.0.0.1:4000/callback among its redirect URIs, exactly the redirectUrl you configure. This draft uses a registered confidential client, and has no code path for dynamic registration. How a client will identify itself with a metadata document instead, with no registration call, is live on the sandbox, and production follows: see Client-ID metadata documents.

import { createAgent, PersonStopped } from "@lifecareid/person-managed-auth/client";

const agent = createAgent({
  resource: "https://lifecare.id/sandbox-source/mcp",  // the MCP endpoint you read from
  issuer: "https://sandbox.lifecare.id",               // the one origin your client secret goes to
  clientId, clientSecret,                              // the client you registered there
  redirectUrl: "http://127.0.0.1:4000/callback",       // one of its registered redirect URIs
  clientName: "My agent",
  onStopped: (stop) => console.log(stop.message),
});

const { result, receipt } = await agent.callTool("read_scope", { scope: "daily", owner }, {
  // Called when the person has to be asked. Show them ask.authorizeUrl; the yes
  // happens there. Return the URL they are redirected to.
  ask: async (ask) => await getTheCallbackFromThePerson(ask.authorizeUrl),
});
// receipt: { consent_id, ledger_entry_hash, access_recorded, scope, tool, at }

owner is the DID that list_scopes returns as token.resource_owner. getTheCallbackFromThePerson shows the person ask.authorizeUrl and returns the URL they are redirected to (or { code, state, iss }), which your own listener at the redirect URI receives. The library rejects a bare code, so the receiver must hand back the callback URL: the redirect receiver in the library's README resolves with the URL. (The receiver on Sandbox data source is for the stock SDK's finishAuth, which takes the code.) The person's yes in the sandbox is described under Saying yes in the sandbox.

What the library does for you:

The credential rule

A credential you hold goes only to the origin you configured for it: the client secret to issuer, the access token to resource. If the server's metadata names a different authorization server, the run stops with a line that names it, before anything is sent. The opt-in is to configure that issuer yourself, with a client registered there. Every request the SDK makes passes through one check before it leaves the process, and redirects are not followed to another origin.

For a server that holds something of a person's

import http from "node:http";
import { createResourceServer } from "@lifecareid/person-managed-auth/server";
import { nodeHandler } from "@lifecareid/person-managed-auth/node";

const pma = createResourceServer({
  resource: "https://api.example.com/read",            // this resource's identifier
  authorizationServer: "https://sandbox.lifecare.id",  // whose tokens you accept
  clientId, clientSecret,                              // your own client there; goes only to that origin
  scopes: ["daily"],
  grantees: "any",                                     // required: "any", a list, a function or "own"
});

http.createServer(nodeHandler(pma, async (request, { grant, receipt }) => {
  return { band: "drifting" };                         // your data; the receipt is added to the answer
}, { scope: "daily" })).listen(8801);

For a Cloudflare Pages Function use pagesFunction from @lifecareid/person-managed-auth/pages. For an MCP endpoint that authorizes each message itself, pass { raw: true } and call authenticate, requireScope and record yourself.

What it does:

  1. Publishes RFC 9728 metadata at its well-known path, naming your resource and the authorization server.
  2. Challenges. Every 401 (no token, or a token that is expired, revoked or for another resource) carries resource_metadata and the one scope you suggest, or the scope the call was for, so a stock client that reconnects after expiry asks for that scope and recovers on its own.
  3. Checks the token at every request. It asks the authorization server and accepts the token only if it is active, an access token, issued to a client you accept (grantees), and, when it names an audience, issued for this resource. Nothing is cached, so a stop holds at the next request. If the authorization server cannot be asked, nothing is served.
  4. Refuses a wrong scope on a single call with 403, error="insufficient_scope", the scope the call asked for, and resource_metadata, so a client knows which scope to ask the person for. A JSON-RPC batch cannot be answered with one status; answer a refused element in band.
  5. Writes the receipt before it answers. One ledger line per read, { subject_did, scope, purpose, accessor, consent_id } and never a value. A read that cannot be written is not served. The receipt (consent_id, access_recorded, ledger_entry_hash) goes back in the answer.

To let a token name your server, register pma.resource, byte for byte, as a resources entry on a client of yours (Sandbox), then have agents ask for it as resource.

grantees is required and has no default; it decides whose token you serve: "any" (many agents read from this server), a list of client ids, a function, or "own" (only your server's own registered client).

Run the examples

Two examples in the kit, one per half, each closing the loop with a synthetic person against the hosted sandbox: discover, the person grants, read, the receipt, the person revokes, the next read is refused. Each takes a few seconds of machine time against the hosted sandbox; a person following the kit's README takes minutes. Wiring the client half into your own agent, with a redirect receiver, is the afternoon.

git clone https://github.com/enbarca/lifecareid-sandbox && cd lifecareid-sandbox
npm ci --prefix lib/person-managed-auth
LIFECAREID_DEVACCESS_TOKEN=... node examples/person-managed-auth/agent.mjs
LIFECAREID_DEVACCESS_TOKEN=... node examples/person-managed-auth/server.mjs

In both, the person's yes and revoke are made with a synthetic identity's session, as the sandbox walkthrough does, and the example says so where it happens. The revoke is POST /v1/consent/revoke with Authorization: Bearer lcs_..., a credential the hosted sandbox requires as production does. A real agent hands the person the URL. Since 2026-11-04 the hosted sandbox accepts a resource you register on your own client, so the server example registers its loopback address as a resource and takes its grant through the authorization code flow, like the agent example, with a token whose aud is that address.

Use it from your own project

Until the package is published, clone the kit, run npm ci --prefix lib/person-managed-auth, and import from lib/person-managed-auth/src/client.js (and server.js, node.js, pages.js) by relative path. To make the package imports in the snippets above resolve, install the folder in your own project (walked on 2026-11-04):

git clone https://github.com/enbarca/lifecareid-sandbox
npm ci --prefix lifecareid-sandbox/lib/person-managed-auth
npm install ./lifecareid-sandbox/lib/person-managed-auth

What draft 1 does not settle

Question Where it stands
Public clients with no secret Not in this draft. The issuer refuses a data scope to the operator-listed native clients that have no secret; on the sandbox, a client identified by a client-ID metadata document holds no shared secret and receives one. The profile will decide with Client ID Metadata Documents. There is no dynamic registration code path.
Several scopes in one token Refused by the issuer. The client asks for one scope and steps up for the next; the union is the profile's question.
The shape of the receipt Follows the hosted sandbox source today. The profile defines it in draft 1.
The introspection and ledger-write paths The paths LifeCare.ID® uses under the issuer, /v1/token/introspect and /v1/access/record. The server half can override them.
Revoked against expired The standard 401 does not tell them apart. The client uses its own clock, and on a first-use refusal it also asks the authorization server about its own token.
Other languages JavaScript first; a Python port is planned.

What it is not