Data access and the personal-data read ledger
Who may read which data, and the record that they did. Two things live here: data access (who is allowed to read a restricted slice of a dataset) and the read ledger (one audit row for every read of personal data). Both are enforced by the server; the dashboard only shows them.
Data classes
| Class | What it is | Default | Needs pii:read |
|---|---|---|---|
person_level |
Who did what: subjects, their events, the identity ledger | restricted | yes |
replay |
Recorded sessions of a person | restricted | yes |
survey_response |
An answer someone gave, with the identity they gave | restricted | yes |
aggregate |
Counts and rates over a cohort at or above the project's floor | unrestricted | no |
telemetry |
Spans, logs, metrics and error events: about the software | unrestricted | no |
The defaults are the decision taken in code (OD-DP-07): person-level product data is restricted until an organization says who may read it. An organization changes the mode of a class; it cannot add a class or change what a class is.
Who may read a person
Reading a person is a person's act. A call is refused before the organization's policy is read
when the caller is an agent, a service, an OAuth client (even for the person who authorized it), a
delegated call, or an organization CI token. A person whose token lacks the human-only pii:read
scope is refused with that scope named. After that, in order: the caller must be able to read the
project, the project's product analytics must be enabled (the PA-01 gate, answered 422 analytics_not_enabled otherwise), and the organization's policy must admit them.
There is no MCP tool for person-level data. An agent that needs it asks the person to read it in the dashboard.
Modes and scopes
A scope names a slice of one class, by one attribute, and the people who may read it:
| Attribute | Example |
|---|---|
project |
project = * (every project) |
environment |
environment = production |
service.name |
service.name = payments (telemetry only) |
event_property:<name> |
event_property:plan = enterprise |
host_tag:<name> |
host_tag:tier = db (telemetry only) |
* as a value means every value of that attribute. A scope's people are users, teams of this
organization or organization roles. Rows inside a scope's slice are readable only by its
people, in whatever mode the class is. Rows outside every scope follow the class's mode:
unrestricted lets anyone who holds the right permission read them; restricted lets nobody until
a scope admits them. Two scopes that contain the same row are an OR.
An agent is judged as the person it acts for, so it can never read a slice that person cannot. An
agent with no person behind it is on nobody's list, even though it holds an organization role of
its own: a scope naming role: MEMBER admits the members who are people, and a scope's user
entries can name only people.
A restricted dataset that is not about a person (telemetry by service.name, aggregates by an
event property) is checked with assertScopeAdmits. For aggregates, which are product analytics,
it also takes the project, which must belong to the organization, and refuses with
analytics_not_enabled until that project's analytics gate is open.
A scope is versioned. Every change adds a version holding the state it produced, and
restoreVersion writes an exact earlier state back as a new version; history is never
rewritten. expectedVersion makes a write a compare-and-set (409 stale_version).
Changing it
Creating or changing a scope, and setting a class's mode, are human-only acts (org:admin,
so an organization owner): a person's own signed-in session, not a token, an agent or an OAuth
client. Each writes an audit row with before and after, in the same transaction as the change,
and tells the owners afterwards.
| Route | Does | Who |
|---|---|---|
GET /orgs/:o/data-access?project= |
What you may read of each class, in which tier, and the cohort floor | any member |
GET /orgs/:o/data-scopes |
Every scope | owner |
POST /orgs/:o/data-scopes |
Create a scope (data_scope.create) |
owner, in a session |
GET /orgs/:o/data-scopes/:id |
One scope and its versions | owner |
PATCH /orgs/:o/data-scopes/:id |
Change principals, archive, or restoreVersion (data_scope.update) |
owner, in a session |
GET /orgs/:o/data-access-defaults |
The mode of each class | owner |
PUT /orgs/:o/data-access-defaults |
Set one or more modes (data_access_default.update) |
owner, in a session |
data_access_get (MCP, read, project:read) answers the same question as the first route for an
agent: the mode of each class, the tier it will be served (stored, sampled_agent, aggregate
or refused), the scopes that bind it, and the project's cohort floor. Scopes that carve a slice
out for other people are counted, never described. A scope's attribute text is untrusted data.
The read ledger
Every read that returns personal data writes one audit row, data.read, after the read, and
the read fails if the row cannot be written: data that was taken but not recorded is not
handed over.
A row holds the surface (dashboard, api, mcp, worker, cli), the tool or route, the data
class, the tier the data was held in, the categories of personal data that came back with
their counts (email, phone, ip_address, name, user_id, device_id, location,
payment_card, government_id, credential, free_text, other), how many rows, the approval
it ran under when one applied, where it went next (client or model_provider), and the digest
of the query. It never holds a value, an identifier or the query text. The actor fields are the
same as every other audit row: who, in which mode, through which transport and credential, for
which client.
Volume. A read of the stored tier, or one that returned any category, is one row per call. A read that returned only aggregates and no category is one row per principal, session and hour, flushed every 60 seconds and on shutdown. It is never sampled.
audit_read_counts (how much each MCP principal read, by hour) also carries the categories.
For a developer adding a person-level read
const { orgId, admission } = await assertPersonLevelRead(principal, 'person_level', { projectId })
return ledgeredRead(ctx, { orgId, projectId, dataClass: 'person_level', surface: 'api',
route: 'GET /…', tier: 'stored', egress: 'client', query }, async () => {
const rows = await read(admission) // filter by admission.admitsRow / slices
const { value, manifest } = scrubValue(rows, { tier: 'agent' })
return { value, manifest, rowCount: rows.length }
})
api/test/data-access/ledger-coverage.test.ts fails for a file that calls these and has no driver
there, so a reader cannot land without its row being checked.