> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Subject Requests

> GDPR right-to-erasure and right-to-portability flows — how members submit deletion/export requests and how org admins process them.

## Overview

A **data subject request (DSR)** allows any organisation member to request that all their personal data be permanently deleted from that organisation's workspaces. The request goes to the organisation's admins for review before any deletion occurs.

```
Member submits request (fresh sign-in required)
       ↓
Account frozen, member signed out · email with cancel link · org admins emailed
       ↓
Member cancels (email link) → account reactivated, "cancelled" email
Admin rejects (with reason) → account reactivated, email with reason & right to complain
Admin approves → erasure worker runs → "being deleted" email → "deleted" email
```

***

## Subject flow

### Submitting a request

Members navigate to **Settings → Privacy** (`/settings/privacy`). They select the organisation they want data deleted from, optionally add a note, and confirm the request.

**API:**

```
POST /me/data-requests
{ "kind": "erasure", "organisation_id": "<uuid>", "note": "optional note" }
```

**Requirements:**

* Caller must be a member of the specified organisation.
* Caller's JWT must have been issued within the last **10 minutes** (fresh auth required). If not, a `403 Fresh authentication required — please sign in again` is returned.
* Returns `409 Conflict` if an open request already exists for the same (user, organisation) pair.

**After submission:**

* Request is created with `status = pending` and `due_at = now + 30 days`. Notifications go to the account's own email address (a `contact_email` in the body is ignored); it is cleared after the final email.
* The account is **frozen** (`users.frozen_at`): every sign-in path and API key is refused with a message pointing at the cancel link, refresh tokens are revoked, API keys are deactivated and calendar auto-join is paused. `freeze_state` records what was switched off so cancelling or a rejection restores exactly that. The UI signs the member out a few seconds after submitting.
* The member is emailed a cancel link (`/data-requests/cancel?token=…`, 32 random bytes; only its SHA-256 is stored). Org admins are emailed that a request is waiting.

### Cancelling

The emailed link opens `/data-requests/cancel`. Opening it changes nothing (mail scanners prefetch links); the member presses **Cancel my request**.

```
GET  /data-requests/cancel?token=…   → { organisation_name, due_at } or 404
POST /data-requests/cancel { token } → cancels if still pending, else 404
```

Both are public, token-gated and rate limited. Cancelling only succeeds while the request is `pending`; it unfreezes the account, logs `erasure_cancelled` and emails a confirmation.

### Viewing requests

```
GET /me/data-requests
```

Returns all the authenticated user's requests, most recent first.

***

## Org admin flow

Users with `org_admin` (or platform `admin`) role can access the deletion request queue at **Settings → Data requests** (`/settings/data-requests`).

### Where admins see requests

Org admins see their organisation's requests in two places, both rendered by the same inbox: **Settings → Data requests** and, below the access requests, **`/access-requests`**. Platform admins see every organisation's requests at `/admin/data-requests`.

Requests are grouped by type — **Deletion** (red badge) first, then **Export** — and sorted by due date within each group, open requests before closed ones. An open request (pending, approved, executing or failed) turns amber within 7 days of its due date and red once overdue, with the days left or overdue shown.

### Queue

```
GET /organisations/{organisation_id}/data-requests?status=pending
```

Requests are ordered: overdue first (due\_at in the past), then by created\_at descending. Subject name and email are included only for `status = pending` requests to minimise exposure of PII.

### Approving a request

The Approve button opens a confirmation dialog that lists the workspaces in scope and, per workspace, how many sessions the member owns (their content is erased) and how many sessions it holds in total (the member is redacted out of the rest):

```
GET /organisations/{organisation_id}/data-requests/{data_request_id}/scope
```

Only the organisation's own workspaces are named. The member's personal workspaces outside the organisation are covered by the erasure but only counted (`personal_workspace_count`). The endpoint returns `409` unless the request is a pending erasure. Approve stays disabled until the scope has loaded, and when nothing is in scope (approval would fail).

Closed requests (rejected, cancelled, completed) are hidden behind **Show closed requests**.

```
POST /organisations/{organisation_id}/data-requests/{data_request_id}/approve
```

* Caller must not be the subject of the request.
* Sets `status = approved`, stamps `decided_at` and `decided_by`.
* Creates a `jobs` row with `job_type = erasure` (picked up by the erasure worker).
* Links `execution_job_id` on the DSR row.
* Appends a `gdpr_log` entry with `event_kind = erasure_approved`.

### Rejecting a request

```
POST /organisations/{organisation_id}/data-requests/{data_request_id}/reject
{ "reason": "Required — non-empty rejection reason" }
```

* Caller must not be the subject of the request.
* `reason` must be non-empty.
* Sets `status = rejected`, stamps `decided_at`, `decided_by`, `decision_reason`.
* Brief 03 will implement account unfreezing and the rejection email to the subject.
* Appends a `gdpr_log` entry with `event_kind = erasure_rejected`.

***

## Platform admin overview

Platform admins can view all DSRs across every organisation at `/admin/data-requests`.

```
GET /admin/data-requests
```

The subject's name, email and note are only returned while a request is pending. Ordered: overdue first, then by created\_at descending. Approval/rejection is done by an org admin through the org-scoped endpoints.

A `failed` request shows the failure reason and a **Retry erasure** button:

```
POST /admin/data-requests/{data_request_id}/retry
```

It resets the erasure job's attempt budget and republishes it; the worker resumes from the request's checkpoint. Platform admins are also emailed when an erasure fails.

***

## Timelines

| Event | Deadline |
| - | - |
| `due_at` set at | `created_at + 30 days` |
| Overdue threshold | `due_at < now` while `status = pending` |

Overdue requests are highlighted in both the org admin queue and the platform admin overview. The API's data-request notifier (every minute) emails org admins a reminder after **7** and **21** days pending, and at **28** days escalates to platform admins as well (also used when an organisation has no admins). It also sends the subject's "being deleted" and "deleted" emails as the worker moves the request on. Each email is claimed with a conditional update first, so none is sent twice.

***

## What is deleted vs retained

The erasure worker (`erasure` consumer in `rag-worker`, `api/crates/rag-worker/src/erasure.rs`) acts on the request's organisation only: the organisation's workspaces plus any workspace **without** an organisation that the subject owns or belongs to (personal workspaces from the waitlist, workshop workspaces) — the app already shows those inside whichever organisation the user is in (`workspace_matches_current_org`), so they're treated as the organisation's. At the end, workspaces the subject owns leave their view: one that isn't in a team organisation (in their Personal organisation, or in none) is **deleted** even when others were invited to it — personal is personal — cascading its sessions (other members' included), transcripts, jobs & insights, plus its topic graph projection; a team workspace stays for the people still in it, with no owner. Rule: delete everything that can be deleted; keep only what topic history & pattern analysis need, with the subject removed.

Every value the worker blanks out rather than deletes is replaced with the scrub marker `[gdpr-scrubbed:<data_request_id>]` (JSON columns: `{"gdpr_scrubbed": "<data_request_id>"}`). Whoever meets it can see why the content is gone: the id is the `data_subject_requests` row (which names the subject's user id) and `gdpr_log.data_request_id` lists what ran. The admin job views show the "Deleted session" badge for it.

| Data | On approval |
| - | - |
| Audio & audio chunks of the subject's sessions (S3 objects), Recall recordings | Deleted; live Recall bots told to leave. In the subject's Personal workspaces this covers every session, other members' included |
| Transcript segments, session notes, meeting chat, work items, project candidates, session practices, workspace reports built from their sessions | Deleted |
| Transcripts & summaries of the subject's sessions | Text replaced with the scrub marker (rows kept for job history); summary paragraphs deleted |
| Documents the subject uploaded in the organisation | Deleted with their S3 objects, chunks and summaries (paragraphs and evaluations cascade); the workspaces' topic graph is then re-projected without them (older uploads have no uploader and stay) |
| The subject's sessions (`owner_user_id` or `former_owner_user_id`, the latter set when they left or were removed) | Tombstoned (`deleted_at`, title & metadata set to the scrub marker) so concern appearances, pattern cards & insight scores keep their counts; invisible everywhere in the product |
| Topic history | Appearances & drafts from the subject's sessions deleted; topics only they held deleted; revisions they wrote scrubbed and topic heads rebuilt from the remaining sessions ([Topic History](https://docs.kair.is/platform/topic-history.md)) |
| Topic graph | Workspaces are re-projected after topic history is cleaned, so the graph holds no erased session. |
| Speaker data | There are no voiceprints or cross-session speaker identities to erase: both were removed with diarisation. Per-segment speaker labels fall under the transcript row above. Data-subject erasure & data-integrity handling for speakers will be rebuilt in a later wave |
| Shares, access requests, speaker claims, org & workspace memberships, calendar connections, assistant conversations, feedback text | Deleted (feedback ratings kept, comments scrubbed) |
| Retained analytics (moderator insights, evaluation critiques, concern resolution notes, feedback comments) | Free text replaced with the scrub marker, scores kept |
| Moderator extraction traces | Prompt & raw model output (transcript text) replaced with the scrub marker, parsed analyses & errors cleared; timings & model kept |
| Other people's sessions where the subject spoke | Kept as the organisation's record; the subject's speaker claims removed |
| Credentials, devices, MCP calls, waitlist entry, `users` row | Only when no team membership is left after this one (Personal doesn't count; the last team's request also erases the Personal workspaces and drops the Personal membership): credentials deleted, devices unpaired, user row pseudonymised (email = keyed HMAC tag, name = scrub marker) |
| The subject's export archives in this organisation | Completed archives deleted from S3 |
| `audit_trail` | Free text (concern names & resolution notes, judge critiques) is never written there; personal fields stripped from the subject's rows as the last step, including the rows the workspace deletion writes |
| `gdpr_log` | `erasure_started` / `erasure_completed` / `erasure_failed` with `data_request_id`; no personal data |
| PostHog | Person & events deleted when `erasure.posthog` is configured (last organisation only); otherwise delete manually |
| Sentry | Receives no personal data (`sendDefaultPii: false`, users identified by id only), so nothing to delete |

Each step is checkpointed in `data_subject_requests.erasure_checkpoint`, so a failed or redelivered job resumes where it stopped (3 attempts, then the request stays `failed` for review). Workers skip writing results into erased sessions.

The erasure job's own `jobs` row sits in one of the request's workspaces and cascades when that workspace is deleted, so everything that can fail and retry (Recall, S3, PostHog …) runs first. The last step is one transaction: delete the non-team workspaces and the Personal membership, log `erasure_completed`, mark the request `completed` (unfreezing the account if it lives on) and redact the audit trail. If it fails, nothing is committed and the job retries; once it commits the worker treats the missing job row as done.

Requests with `scope = 'personal'` are refused by the worker. Personal data is erased by a request in the person's Personal organisation, decided by a platform admin; in that organisation, the subject's workspaces are deleted outright, shared or not. See [Account ownership](https://docs.kair.is/platform/account-ownership).

***

## Database schema

Key tables added by migration `m20260925_000001_data_subject_requests`:

| Table / column | Purpose |
| - | - |
| `data_subject_requests` | One row per request; tracks status, kind, scope, decision metadata, FK to erasure job |
| `user_organisations.role` | `organisation_role` enum: `member` \| `org_admin` |
| `users.frozen_at` | Set while a request is pending; blocks sign-in & API keys |
| `data_subject_requests.notified_status`, `reminders_sent` | Notifier bookkeeping (last lifecycle email sent, reminders sent) |
| `sessions.deleted_at` | Tombstone set by the erasure worker |
| `documents.uploaded_by_user_id` | Uploader, so erasure can remove a member's own documents |
| `gdpr_log.event_kind` | Promoted from free TEXT to `gdpr_event_kind` enum |

Unique constraint: one open (`pending`, `approved` or `executing`) request per subject, kind & organisation.

***

***

## Export (right to portability)

Users can request a machine-readable archive of their personal data (GDPR Art. 20) or all sessions in a workspace.

For which export applies to which organisation kind, and what each includes, see [Exports](https://docs.kair.is/platform/exports.md).

### Personal export

```
POST /me/export
```

Body (optional): `{ "format": "json" | "csv" | "markdown" }` — defaults to `"json"`.

* Requires a JWT issued within the last **10 minutes** (fresh auth; API keys and OAuth tokens rejected).
* Account must not be frozen.
* Returns `409 Conflict` if an export is already in progress.
* Creates a `data_subject_requests` row with `kind = export`, `scope = personal`, `status = executing` (self-service; no admin approval step).
* Enqueues a `DataExport` job. The `rag-worker` export consumer builds the ZIP on disk, uploads it to `kair-voice/gdpr-exports/<data_request_id>.zip` (retries overwrite the same object) and stores only that key in `freeze_state["s3_key"]` — never a download link.
* The notifier creates a 24-hour presigned link when it sends "Your data export is ready". If it can't (S3 not configured on the API, presigning fails) it logs an error and retries on the next sweep rather than sending an email without a link.
* Archives are deleted from S3 **3 days** after the export finished or failed (hourly sweep in `rag-worker`, `EXPORT_RETENTION`); the request then records `freeze_state["expired_at"]`.
* A failed export is marked `failed` only after its last retry; platform admins then get an "export failed" email with the error.
* **Debug builds only:** the worker also copies each archive and its JSON files, unpacked, to `api/debug/gdpr-exports/<data_request_id>/` (gitignored, kept across builds & `cargo clean` — delete it yourself when done) so exports can be inspected locally — debug builds don't send email.

The ZIP contains:

| File | Contents |
| - | - |
| `manifest.json` | Export version, timestamp, request id, scope, list of files |
| `profile.json` | User record (email, name, role, onboarded\_at; password hash excluded) |
| `memberships.json` | Organisation & workspace memberships |
| `sessions.json` | Sessions the user owns |
| `transcripts.json` | Their transcripts, each with its segments |
| `summaries.json` | Their summaries |
| `notes.json` | The user's session notes (any session) |
| `attributed_segments.json` | Lines in other people's sessions whose speaker label the user claimed — only those lines |
| `assistant_conversations.json` | Assistant conversations & messages |
| `feedback.json` | Pattern-card & answer feedback |
| `audit_events.json` | Audit log entries where the user was the actor (incl. impersonated requests) |
| `data_requests.json` | The user's other data requests |
| `connected_oauth_apps.json` | OAuth grants to connected apps & the pairwise subject ids issued to them |
| `audio/<session_id>/…` | Original uploads and recorded chunks of their sessions |
| `moderator_extraction_traces.json` | Parsed/persisted moderator discourse analyses for sessions the user owns (no prompts or raw model output) |
| `moderator_extraction_traces_PRIVACY.json` | Short pointer to this DPIA section |

#### DPIA: moderator extraction traces in personal exports

Offline evaluation stores full LLM prompts and raw model output in `moderator_extraction_traces` when `moderator_agent.trace_extractions` is enabled. Those fields are **never** included in portability exports.

For owned sessions, the export may include `parsed_analysis` and `persisted_analysis` JSON from that table. Those structures are built from group discussion transcripts and can name or paraphrase other participants. To reduce third-party leakage, the export worker keeps only pattern and speaker-share rows tied to **speaker labels the subject has claimed** in that session (via `speaker_claims`). If the subject has no claim in a session, those analysis fields are omitted. On kept pattern cards, item lists, excerpts, open questions, source context and similar free-text fields are cleared. Divergence/convergence summaries, headlines, and practice outputs are dropped even when claims exist, because they are session-wide.

Erasure scrubs or clears trace rows for sessions the subject owns, holds a speaker claim in, or recorded a track in (browser, registered device, or phone capture while their device was linked to that session). Anonymous phone admissions with only a display name and no linked device cannot be attributed to the subject, so their traces are left to the retention sweep. Retention hard-deletes rows older than `trace_retention_days` (rag-worker sweep).

### Workspace export

```
POST /workspaces/{workspace_id}/export
```

Body (optional): `{ "format": "json" | "csv" | "markdown" }` — defaults to `"json"`.

* Requires workspace **owner** or platform **admin**, a fresh interactive sign-in (same rule as the personal export) and an account that isn't frozen; a token limited to another workspace is refused.
* Returns `409 Conflict` if a workspace export is already in progress for the requester.
* Creates a DSR with `kind = export`, `scope = organisation`.
* The archive holds the workspace's sessions, transcripts (with segments) and summaries — no audio and no members' private notes. Same storage, email and expiry as the personal export.

### Organisation export

```
POST /organisations/{org_id}/export
```

Body (optional): `{ "format": "json" | "csv" | "markdown" }` — defaults to `"json"`.

* Requires org **admin/owner** or platform **admin**, plus a fresh interactive sign-in.
* Returns `409 Conflict` if an org export is already in progress for the requester.
* Creates a DSR with `kind = export`, `scope = organisation`, `organisation_id` set.
* The archive aggregates sessions, transcripts, and summaries across **all workspaces** in the organisation.

### Export formats

| Format | Description |
| - | - |
| `json` | Pretty-printed JSON files per entity type (default) |
| `csv` | One `.csv` per entity type; nested data (e.g. transcript segments) gets its own file w/ FK column |
| `markdown` | One `.md` per section with GFM table rows |

All formats are delivered as a `.zip` archive.

***

## GDPR log event kinds

| `event_kind` | When written |
| - | - |
| `erasure_started` / `erasure_completed` / `erasure_failed` | Erasure worker lifecycle |
| `erasure_approved` | Org admin approves a request |
| `erasure_rejected` | Org admin rejects a request |
| `export_requested` | Personal or workspace export requested |
| `export_completed` | Export archive uploaded |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.