API reference

This document enumerates every HTTP endpoint exposed by the Find My Data server (release 26.7.20.0), for integrators building against the API and reviewers auditing its authorization surface. Every path, capability string, and field name below is taken directly from the route modules mounted in packages/server/src/app.ts; the authorization and error-envelope behavior is defined in packages/server/src/kernel/http.ts and packages/server/src/kernel/errors.ts. Role-to-capability grants are documented in the permissions manifest; the security rationale is in the threat model.

Conventions

All endpoints live under /api/. Requests and responses are JSON unless noted (the Graph webhook validation handshake responds text/plain).
Request bodies are validated with Zod schemas; a failed parse returns 400 validation_failed with per-field issues (see Error envelope).
An optional x-fmd-correlation request header sets the correlation id for the request; otherwise one is generated. Responses carry an x-fmd-auth-mode header (dev or entra) — except the csrf_token_invalid rejection, which is returned before the header is set.
List endpoints are bounded (e.g. assets 200 rows, findings 200, audit 200, scans 50, analyst history 25); there is no cursor pagination in this release.

Capability column legend

Value	Meaning
`capability.string`	The exact string passed to `requireCapability` (`kernel/authz.ts`). Deny by default.
session only	Requires an authenticated session but no specific capability; per-row visibility is enforced in the handler/repository.
none (public)	No session required.
UNAUTHENTICATED (webhook)	Deliberately unauthenticated receiver; trust comes from the Graph validation-token handshake and a per-subscription `clientState` HMAC, never from a session.
dev-mode only	Endpoint exists only in development configuration; any other configuration returns `404` (the endpoint is hidden, not merely forbidden).

Authentication model

Authentication is a signed session cookie named fmd_session (SESSION_COOKIE in kernel/http.ts): httpOnly, SameSite=Lax, Secure when FMD_ENV=production, path /. The cookie value is an HMAC-signed session id; the server resolves it to a session row and loads the authorization context (tenant, principal, roles, owned domains) per request. Client-supplied identity fields are never trusted. Two auth modes exist (ADR-0004):

Dev mode (FMD_AUTH_MODE=dev, development only). Login flow:
1. GET /api/auth/dev/personas — list seeded principals with roles.
2. POST /api/auth/dev/login with { "principalId": "..." } — sets the cookie and returns { ok, csrfToken, authMode }.
Production refuses dev mode twice: the process fails to boot with FMD_AUTH_MODE=dev when FMD_ENV=production (kernel/config.ts), and the request middleware rejects any surviving dev-mode session at request time (kernel/http.ts).
Entra mode (FMD_AUTH_MODE=entra) — Microsoft Entra OIDC sign-in (ADR-0035), live-validated. GET /api/auth/entra/login starts an authorization-code + PKCE (S256) flow and GET /api/auth/entra/callback completes it: the ID token’s signature is validated against the tenant JWKS before any claim is trusted, and identity binds by immutable issuer+subject, never email. When the app registration is not configured, login returns an explicit 501 not_configured — never a silent fallback.

CSRF

Every mutating request (POST, PUT, PATCH, DELETE) made with a session must send the session’s CSRF token in the x-fmd-csrf header. The token is returned by POST /api/auth/dev/login and by GET /api/auth/me. A missing or wrong token returns 403 {"error":"csrf_token_invalid"}. Requests without a resolved session skip the CSRF check — this is what allows the unauthenticated Graph webhooks and the dev login itself to POST.

401 / 403 / 404 semantics

Status	When
`401 authentication_required`	No valid session on an endpoint that requires one.
`403 not_permitted`	Authenticated but missing the required capability. Every denial is appended to the audit log as `authorization_denied` with the capability as the policy decision.
`403 csrf_token_invalid`	Mutation without a valid `x-fmd-csrf` header.
`404 not_found`	Resource missing — or the resource exists but belongs to another tenant or a business domain the caller cannot see. Cross-scope probes get 404, not 403, so existence never leaks (`NotFoundError` in `kernel/errors.ts`; tested in the security suite).

Authorization is capability-based, not role-based: handlers call requireCapability(auth, "..."), and capabilities are granted per role at either tenant scope or domain scope (resolved against active ownership assignments). Domain-scoped list endpoints additionally apply domainScopeFilter so results are constrained to the caller’s owned domains. See the permissions manifest for the full role/capability matrix.

Error envelope

The central error handler (kernel/http.ts) maps typed errors (kernel/errors.ts) to a uniform envelope:

{ "error": "<code>", "message": "<human-readable>" }

Variants:

Zod validation failures: { "error": "validation_failed", "issues": [{ "path": "field.path", "message": "..." }] } (400).
CSRF failures: { "error": "csrf_token_invalid" } (403, no message).
Unhandled errors: { "error": "internal_error", "correlationId": "..." } (500) — no stack or details leak.

Code	HTTP	Source
`validation_failed`	400	`ValidationError` / Zod parse failure
`authentication_required`	401	`AuthnError`
`not_permitted`	403	`AuthzError` (audited)
`csrf_token_invalid`	403	CSRF middleware
`not_found`	404	`NotFoundError` (incl. cross-tenant/cross-domain probes)
`conflict`	409	`ConflictError` (e.g. state-machine violations)
`blocked_capability`	422	`BlockedError` — the operation is implemented but its live integration is feature-gated off or its credentials do not resolve. The honest “built but not enabled here” signal, distinct from other 4xx caller errors.
`internal_error`	500	Unhandled exception
`not_configured`	501	Entra OIDC endpoints when the app registration is unconfigured (literal response, not an `AppError`)

Endpoint reference

94 endpoints across 15 route modules, in mount order from packages/server/src/app.ts.

Health (`routes/health.ts`)

Liveness and honest readiness. No authentication.

Method	Path	Capability	Purpose
GET	`/api/health`	none (public)	Liveness: `{ "status": "ok" }`.
GET	`/api/ready`	none (public)	Readiness: DB check plus per-integration mode report. `503` when the DB check fails.

GET /api/ready returns { status, dbOk, env, integrations } where each integration (connector, aiProvider, entraSignIn, purviewLabelRead, purviewLabelWrite, changeNotifications, teamsConnector, exchangeConnector, onedriveConnector, azureStorageConnector, smbConnector, sqlConnector, gdriveConnector, boxConnector) reports one of:

mock — the deterministic fixture path is in use,
live — feature enabled and its secret reference actually resolves to a value,
blocked — feature enabled but credentials do not resolve (never reported as live),
disabled — feature turned off.

Two integrations depart from the general blocked/disabled split: purviewLabelRead and purviewLabelWrite report blocked (never disabled) whenever they are not fully live — including when their feature flag is simply off — and entraSignIn reports live when the app registration and secret reference resolve, blocked when FMD_AUTH_MODE=entra but the registration is unconfigured, and disabled outside entra mode. changeNotifications additionally requires a public webhook URL (FMD_WEBHOOK_PUBLIC_URL) to report live. The six per-source connectors (onedriveConnector, azureStorageConnector, smbConnector, sqlConnector, gdriveConnector, boxConnector) additionally report blocked (never a silent empty scan) when enabled without an explicit selection, and blocked rather than disabled while de-selected scopes persist un-reconciled.

Auth (`identity/auth-routes.ts`)

Method	Path	Capability	Purpose
GET	`/api/auth/mode`	none (public)	Report `{ env, authMode, devBannerRequired }` so the UI can show the dev-identity banner.
GET	`/api/auth/dev/personas`	dev-mode only	List seeded active user principals with roles for the login picker. `404` outside dev env + dev auth mode.
POST	`/api/auth/dev/login`	dev-mode only	Start a session as a seeded principal. Body `{ principalId }`; returns `{ ok, csrfToken, authMode }` and sets `fmd_session`. Audited as `dev_login`. `404` outside dev.
POST	`/api/auth/logout`	none (public)	Revoke the session (if any) and clear the cookie; returns `{ ok: true }` even without a session (CSRF header required while logged in). Audited when a session was revoked.
GET	`/api/auth/me`	session only	Current principal: `{ principalId, tenantId, authMode, displayName, title, department, roles, ownedDomains, csrfToken }`. `401` without a session.
GET	`/api/auth/entra/login`	none (public; entra mode only)	Start the Entra OIDC authorization-code + PKCE sign-in: `302` to the Microsoft authorize endpoint when configured, `501 not_configured` when the app registration is not. `404` unless `FMD_AUTH_MODE=entra`.
GET	`/api/auth/entra/callback`	none (public; entra mode only)	OIDC redirect target: verifies flow cookie + `state`, exchanges the code, validates the ID token (signature-before-claims), resolves/JIT-provisions the principal, sets `fmd_session`. Audited as `entra_login`.

Governance (`governance/routes.ts`)

Onboarding, taxonomy lifecycle (draft → human review → approval), and ownership assignment. AI-generated taxonomy objects are always drafts pending human review.

Method	Path	Capability	Purpose
GET	`/api/onboarding/profile`	`tenant.profile.read`	Read the organization profile.
POST	`/api/onboarding/profile`	`tenant.profile.write`	Upsert the org profile. Body: `name`, `industries[]`, `geographies[]`, `description`. Returns `{ profileId }`.
POST	`/api/onboarding/policy-documents`	`governance.policy.ingest`	Upload a policy document for section parsing + citations. Body: `title`, `filename`, `text`.
GET	`/api/onboarding/policy-documents`	`governance.policy.read`	List uploaded policy documents.
POST	`/api/onboarding/generate-taxonomy`	`governance.taxonomy.propose`	Generate a draft taxonomy via the AI gateway (ADR-0005). Response includes `provider`, `model`, and a note that all objects are drafts.
GET	`/api/governance/ai-usage`	`governance.usage.read`	Tenant AI usage + estimated cost of model building on the customer’s own provider (per-task run counts, tokens, `estCostUsd`, `totalEstCostUsd`, `hasUnpricedUsage`). Admin/oversight only (platform_admin, governance_admin, auditor) — not domain owners. Estimates; the provider bills the customer directly.
GET	`/api/governance/taxonomy`	`governance.taxonomy.read`	List domains + information types; domain-scoped callers see only their domains.
PATCH	`/api/governance/domains/:id`	`governance.taxonomy.admin`	Edit a domain. Body (all optional): `name`, `description`, `inclusion`, `exclusion`.
POST	`/api/governance/domains/:id/approve`	`governance.taxonomy.approve`	Approve a draft domain.
PATCH	`/api/governance/information-types/:id`	`governance.taxonomy.admin`	Edit an information type. Body (all optional): `name`, `definition`, `sensitivityRationale`, `expectedLocationNote`.
POST	`/api/governance/information-types/:id/approve`	`governance.taxonomy.approve`	Approve a draft information type.
GET	`/api/governance/owner-suggestions`	`governance.owner.assign`	Evidence-ranked owner suggestions for `?domainId=`.
POST	`/api/governance/owners`	`governance.owner.assign`	Assign an owner. Body: `principalId`, `domainId`, `kind` (`owner`\|`delegate`\|`steward`, default `owner`), `attestationDays?` (1–730). Returns `{ assignmentId }`.
GET	`/api/governance/owners`	`governance.taxonomy.read`	List owners, optionally `?domainId=`. A domain-scoped reader asking about a foreign domain gets an empty list.
GET	`/api/governance/labels`	`governance.taxonomy.read`	Sensitivity-label catalog.
POST	`/api/domains/:id/attest`	session only	Attest the domain’s posture: gated on an active ownership assignment for the caller (signing is an identity act, not a granted verb), appends a counts-only attestation ledger row (no content).

Scan (`scan/routes.ts`)

Connector registration and durable scan campaigns (ADR-0007, ADR-0008). The mock M365 connector is the default/CI path; the live Graph connector is implemented and has been validated read-only against a live Microsoft 365 tenant (ADR-0013). Scope visibility: tenant-scoped readers (admin/auditor) see all scopes; a domain-scoped owner sees scopes governed by their domains or holding at least one asset classified into them.

Method	Path	Capability	Purpose
POST	`/api/sources/connect`	`connector.configure`	Register every configured connector family — M365 (SharePoint + OneDrive), Azure Storage, SMB shares, SQL databases, Google Drive, Box — creating/reusing one instance per family, registering discovered scopes, and draining scopes whose selection entry was removed. Returns `{ connectorInstanceId, scopesRegistered, mode }` plus per-family instance ids (`azureConnectorInstanceId`, `smbConnectorInstanceId`, `sqlConnectorInstanceId`, `gdriveConnectorInstanceId`, `boxConnectorInstanceId`; `null` when not configured) and per-family `*Blocked` reasons when a family’s credentials do not resolve. Audited.
GET	`/api/sources`	`scan.job.read`	List visible source scopes with coverage state, asset count, and delta-cursor status.
POST	`/api/sources/:id/expectation`	`governance.taxonomy.admin`	Set/clear the governed location expectation. Body: `{ domainId: string \| null }`. `404` for unknown scope. Audited.
POST	`/api/scans`	`scan.job.create`	Create a scan campaign. Body: `{ scopeId, kind: "inventory" \| "delta" }`. Returns `{ campaignId }`.
POST	`/api/scans/:id/:action`	`scan.job.pause` / `scan.job.resume` / `scan.job.cancel`	Transition a campaign; `:action` ∈ `pause`\|`resume`\|`cancel`, and the capability checked is `scan.job.<action>`.
GET	`/api/scans`	`scan.job.read`	List campaigns (50 most recent) for visible scopes. Tenant-wide model-rescore campaigns (no scope) are visible to tenant-scoped readers only.
GET	`/api/scans/:id`	`scan.job.read`	Campaign status/progress. Domain-scoped callers get `404` for campaigns outside their visible scopes (no existence leak).
POST	`/api/dev/fixture/mutate`	dev-mode only + `connector.configure`	Demo change-sequence controls against the mock tenant only (`404` unless dev env and `connectorMode=mock`). Body: `scopeExternalId`, `action` ∈ `add`\|`edit`\|`rename`\|`overshare`\|`restrict`\|`set_label`\|`clear_label`\|`delete`\|`request_resync`, plus optional `fileId`, `content`, `name`, `labelGuid`.

Models (`routes/models.ts`)

Governed dataset curation and model-release lifecycle with separation of duties (approver ≠ proposer, enforced in models/pipeline.ts). This loop has been validated end-to-end against live Microsoft 365 data.

Method	Path	Capability	Purpose
POST	`/api/models/rescore`	`model.release.approve`	Release a new ensemble version and re-score retained features — no source I/O.
GET	`/api/models/releases`	`governance.taxonomy.read`	List ensemble and detector releases.
GET	`/api/models/dataset-candidates`	`model.dataset.curate`	List dataset candidates, optional `?status=` (`pending`\|`approved`\|`rejected`).
POST	`/api/models/dataset-candidates/:id/decide`	`model.dataset.curate`	Curate a candidate. Body: `{ decision: "approved" \| "rejected" }`.
GET	`/api/models/datasets`	`model.dataset.curate`	List dataset snapshots.
POST	`/api/models/datasets`	`model.dataset.curate`	Create a consented, cluster-aware train/eval snapshot. Body: `name`, `description?`, `consentScope?` (`tenant_internal`\|`vendor_shareable`), `evalFraction?` (0.1–0.9).
GET	`/api/models/governed-releases`	`governance.taxonomy.read`	List governed model releases with lifecycle state.
POST	`/api/models/releases/propose`	`model.release.propose`	Propose a release. Body: `configPatch` (optional threshold/boost overrides: `candidateThreshold`, `reviewLowThreshold`, `reviewHighThreshold`, `nearDupConfirmedBoost`, `exactDupConfirmedBoost`, each 0–1), `datasetSnapshotId?`, `rationale?`.
POST	`/api/models/releases/:id/evaluate`	`model.release.propose`	Evaluate candidate vs. current on held-out labels (precision/recall/F1).
POST	`/api/models/releases/:id/approve`	`model.release.approve`	Approve (separation of duties: self-approval is rejected).
POST	`/api/models/releases/:id/reject`	`model.release.approve`	Reject a proposed release.
POST	`/api/models/releases/:id/promote`	`model.release.approve`	Promote: bump the active ensemble and trigger a source-free rescore.
POST	`/api/models/releases/:id/rollback`	`model.release.approve`	Roll back to the prior release.

Review (`review/routes.ts`)

The “Is this yours?” owner review queue. Decisions create linked OwnerConfirmed assertions — the original inference is never destroyed — and propagate to cluster/container neighbors without auto-confirming. Decisions are revisable within limits.

Method	Path	Capability	Purpose
GET	`/api/review/queue`	`review.read`	List pending candidates, optional `?domainId=`; domain-scoped to the caller.
GET	`/api/review/candidates/:id`	`review.read`	Candidate detail with evidence (excerpts are capability-gated and audited; cross-domain probes `404`).
POST	`/api/review/candidates/:id/decision`	`review.decide`	Record a decision. Body: `decision` ∈ `mine`\|`mine_different_type`\|`another_domain`\|`mine_not_sensitive`\|`not_a_match`\|`need_more_evidence` (from `@fmd/shared` `REVIEW_DECISIONS`), plus `correctedInformationTypeId?`, `routedDomainId?`, `note?` and `trainingEligible?`.
POST	`/api/review/decisions/:id/revise`	`review.decide`	Undo/revise a decision: restores the candidate, supersedes the human assertions, re-scores propagated relatives, and watermarks the decision out of dataset curation/snapshots; refused (`409`) once consumed downstream.
GET	`/api/assets/:id/propagation-preview`	`review.read`	Side-effect-free family/folder propagation preview (foreign-domain members redacted), used by the Family Plate and batch-extend.

Analyst (`analyst/routes.ts`)

Typed, scoped query answering over the search projection (ADR-0009). Plans — whether deterministic or AI-proposed — are validated identically, and tenant/domain predicates are injected server-side; a plan cannot widen its scope.

Method	Path	Capability	Purpose
POST	`/api/analyst/query`	`analyst.query`	Answer a question. Body: `question` (3–2000 chars), `planner` (`deterministic` default, or `ai`). With `planner:"ai"` the provider sees only scope-visible display names delimited as untrusted data. Returns `{ answer }` with interpretation, scope, evidence rows, coverage, and freshness.
GET	`/api/analyst/history`	`analyst.query`	The caller’s own last 25 queries (principal-scoped, not tenant-wide).

Actions (`actions/routes.ts`)

Approval-gated remediation state machine (ADR-0010): draft (with preview + justification) → submit → approve → execute → verify from source. internal_task runs fully in-product. purview_label_set / purview_label_remove are built and offline/mock-validated; the live Graph write path is feature-gated (FMD_FEATURE_PURVIEW_LABEL_WRITE + a separate remediation identity) and refuses honestly when unconfigured: the draft is recorded with status: "blocked" and a blockedReason, and submitting a blocked action returns 409 conflict (a live connector whose base Graph credentials do not resolve fails earlier with 422 blocked_capability). Live label writes have not been exercised against a real tenant.

Method	Path	Capability	Purpose
POST	`/api/actions`	`action.draft`	Draft an action with preview. Body: `kind` ∈ `internal_task`\|`purview_label_set`\|`purview_label_remove`, `targetAssetId`, `justification` (required, min 10 chars), plus `findingId?`, `desiredLabelGuid?` (required for `purview_label_set`), `taskTitle?` (required for `internal_task`), `taskNote?`.
GET	`/api/actions`	session only	List actions (100 most recent). Callers with `action.approve` or `audit.read` see all; others see only actions in their owned domains (enforced in `listActions`). `?mine=true` filters to the caller’s own requests (applied after visibility, never widening it).
POST	`/api/actions/:id/submit`	`action.submit`	Submit a validated draft for approval.
POST	`/api/actions/:id/approval`	`action.approve`	Approve or reject. Body: `{ decision: "approve" \| "reject", reason? }` (`reason` defaults to empty). Separation of duties (strict): a requester cannot approve their own action, and an approver who owns the action’s target domain is also refused — an owner never approves changes to their own domain’s data. Denials are audited as `approval_self_dealing_denied`.
POST	`/api/actions/:id/repreview`	`action.draft`	Re-preview after source drift invalidates the captured state.

Read models (`routes/read-models.ts`)

Owner-facing read surface. Every query is tenant-scoped; domain-scoped capabilities filter to owned domains. Evidence levels are tiered (metadata < summary < excerpt); excerpt reads require asset.evidence.excerpt.read and are audited.

Method	Path	Capability	Purpose
GET	`/api/home`	session only	Owner home: per-owned-domain posture (asset counts, pending review, open findings, unlabeled count, 7-day changes, attestation), plus capability-conditional sections (`pendingApprovals` under `action.approve`, `draftTaxonomy` under `governance.taxonomy.approve`, `scopes` coverage under `scan.job.read`).
GET	`/api/landscape`	`asset.metadata.read`	”My Data Landscape” grouped cells: domain × information type × scope × provenance × label state × risk severity.
GET	`/api/assets`	`asset.metadata.read`	Asset list (max 200). Filters: `?q=` (FTS; input is sanitized and quoted so operators like AND/OR/NEAR are literal terms), `?informationTypeId=`, `?labelState=`, `?riskSeverity=`, `?provenance=` (`confirmed`\|`inferred`), `?reach=` (observed-reach band) — the latter two are the Reach-Plate drill filters.
GET	`/api/landscape/exposure-flow`	`asset.metadata.read`	Per-asset maximum observed reach × confirmed/inferred provenance for `?domainId=` (required), grouped for the Reach Plate flow.
GET	`/api/assets/:id`	`asset.metadata.read`	Asset detail: location + version history, current label observation, permissions (with completeness caveat), risk components, assertion provenance chain, findings, clusters. `excerpts` is populated only under `asset.evidence.excerpt.read` (audited as `asset_excerpts_read`); `sourceUrl` is a deep link that relies on the user’s own source permission. `404` for missing or non-visible assets.
GET	`/api/assets/:id/connections`	`asset.metadata.read`	Bounded graph neighborhood (depth 2, max 30 nodes) with per-edge reasons. Assets in domains the caller cannot see are redacted (`label: "(asset in another domain)"`) and never expanded.
GET	`/api/assets/:id/semantic-neighbors`	`asset.metadata.read`	Embedding-cosine neighbors (LSH retrieval, min cosine 0.55, top 8) filtered by the same visibility rule — semantic discovery never leaks a foreign-domain document.
GET	`/api/findings`	`finding.read`	Findings (max 200), severity-ordered. `?status=` defaults to open-ish states (`open`/`acknowledged`/`reopened`); `?status=all` includes resolved. Domain-filtered for scoped callers.
GET	`/api/ops/overview`	`operations.read`	Operations: work-queue status counts, dead letters (50), tenant-filtered recent logs (100), scanner fleet health.
GET	`/api/ops/metrics`	`operations.read`	Telemetry snapshot: counters, latency histograms, and DB-derived gauges (queue pending/leased, dead letters, oldest pending age, delta-cursor lag, content-state distribution).
GET	`/api/audit`	`audit.read`	Hash-chained audit trail (200 most recent), optional `?category=` filter.

Admin (`admin/routes.ts`)

Setup progress, runtime + tenant settings, and a connectivity probe. Secrets are never returned — only booleans derived from configuration references.

Method	Path	Capability	Purpose
GET	`/api/admin/setup-state`	`tenant.profile.read`	Onboarding checklist derived from observable state.
GET	`/api/admin/settings`	`tenant.profile.read`	Runtime config (read-only, secrets as booleans) + tenant settings + evidence-level note.
PATCH	`/api/admin/settings`	`tenant.profile.write`	Update tenant settings. Body (optional): `dataHandlingProfile` ∈ `minimized_evidence`\|`metadata_only`\|`enhanced_evidence`, `name`. Changing the profile bumps the tenant config version, invalidating evidence-bearing stage caches.
POST	`/api/admin/connector/test`	`connector.test`	Probe connector connectivity without a scan. Mock is always healthy; live acquires an app-only Graph token and does one cheap read (validated against a live Microsoft 365 tenant). Missing credentials surface as `ok:false` with a safe reason — never a 500, never a secret. Audited.

Notifications (`notifications/routes.ts`)

Graph change-notification lifecycle: built end-to-end and validated via the dev simulator, which drove a real read-only delta reconcile against a live Microsoft 365 tenant. Live Graph subscription delivery additionally requires FMD_FEATURE_CHANGE_NOTIFICATIONS=true and a public HTTPS receiver URL (FMD_WEBHOOK_PUBLIC_URL); /api/ready reports the mode honestly. A notification is treated as a hint that triggers delta reconciliation — notification content is never trusted.

Method	Path	Capability	Purpose
POST	`/api/webhooks/graph/notifications`	UNAUTHENTICATED (webhook)	Graph change-notification receiver. Returns `202` fast regardless of per-item outcome.
POST	`/api/webhooks/graph/lifecycle`	UNAUTHENTICATED (webhook)	Graph subscription lifecycle-event receiver (`202`).
POST	`/api/admin/notifications/subscribe`	`connector.configure`	Create a change subscription for a scope. Body: `{ scopeId }`.
GET	`/api/admin/notifications/subscriptions`	`operations.read`	List subscriptions with expiry state.
GET	`/api/admin/notifications/recent`	`operations.read`	Recent notifications and their outcomes (reconciled / deduplicated / rejected).
POST	`/api/admin/notifications/renew`	`connector.configure`	Renew subscriptions nearing expiry; returns `{ renewed }`.
POST	`/api/dev/notifications/simulate`	dev-mode only + `connector.configure`	Development injector (`404` outside dev): ensures a mock subscription for `{ scopeId }` and drives the real receiver + reconcile path without a public endpoint.

Webhook trust model (both unauthenticated endpoints):

Validation handshake — a request with a ?validationToken= query parameter is echoed back as text/plain 200 (Graph’s subscription-creation check).
clientState HMAC — each subscription’s clientState is derived as HMAC-SHA256(sessionSecret, "fmd-sub:<subscriptionId>") (deriveClientState) and compared in constant time (constantTimeEquals). On the notifications receiver, ingestNotification rejects any item whose clientState does not verify before any side effect, and deliberately does not persist rejected rows (an unauthenticated caller who learns a subscription id must not be able to amplify writes); a metric records the rejection. On the lifecycle receiver, the same constant-time check runs before handleLifecycleEvent — an absent or wrong clientState is skipped, so an unauthenticated caller cannot force a reconcile or tamper with a subscription.
Verified notifications are deduplicated within a time window and enqueue a delta reconcile; the payload itself is never treated as content.

Teams (`teams/routes.ts`)

Teams connector surface — built and mock-validated; the live Graph adapter is feature-gated behind FMD_FEATURE_TEAMS_CONNECTOR (requires the protected ChannelMessage.Read.All permission) and has not been run live. Channel file attachments canonicalize to their backing SharePoint driveItem, so no duplicate asset identities are created. Read views require tenant-scoped operations.read because Teams messages are not yet mapped to business-domain ownership — deny-by-default until they are.

Method	Path	Capability	Purpose
POST	`/api/teams/sync`	`connector.configure`	Sync teams → channels → messages (and canonicalize file attachments). Returns `{ summary, mode }`.
GET	`/api/teams`	`operations.read`	List synced teams/channels.
GET	`/api/teams/channels/:id/messages`	`operations.read`	Messages for a channel (identifier-redacted previews).

Exchange (`exchange/routes.ts`)

Exchange connector surface — built and mock-validated; live is feature-gated behind FMD_FEATURE_EXCHANGE_CONNECTOR (Mail.Read scoped to selected mailboxes via FMD_EXCHANGE_MAILBOXES) and has not been run live. An attachment is a copy: a content match to a SharePoint asset is recorded as similarity, not identity. Read views require tenant-scoped operations.read for the same deny-by-default reason as Teams.

Method	Path	Capability	Purpose
POST	`/api/exchange/sync`	`connector.configure`	Sync selected mailboxes via per-folder message delta. Returns `{ summary, mode }`.
GET	`/api/exchange`	`operations.read`	List synced mailboxes/folders.
GET	`/api/exchange/folders/:id/messages`	`operations.read`	Messages for a folder.

Control plane (`controlplane/routes.ts`)

Signed licensing entitlement — tokens are verified locally, with an offline grace window; online activation and renewal contact Find My Data Control only when a Control URL is configured — and strictly allowlisted fleet-health telemetry with a transparency preview and customer opt-out. This module also defines the deployment’s PRODUCT_VERSION.

Method	Path	Capability	Purpose
GET	`/api/controlplane/entitlement`	`tenant.profile.read`	Entitlement state: `{ state, reason, source, edition, features, term, offlinePolicy, deploymentId, connectorFamilies, usage, events }`. `state` is `active`/`grace`/etc., or `unlicensed` when no token/secret is configured. `edition` is `free` or `paid` (ADR-0037); tokens issued before the two-tier model report `evaluation`/`standard`/`enterprise` until their next renewal.
POST	`/api/controlplane/activate`	`tenant.profile.write`	Offline activation: verify and store a signed entitlement token. Body: `{ token }`. Returns `422` when the token does not verify.
POST	`/api/controlplane/activate-online`	`tenant.profile.write`	Online activation: exchange an activation code for a signed entitlement, which is verified locally and tenant-bound before it is trusted. Body: `{ activationCode, deploymentPseudonym? }`. Returns `422` on failure.
POST	`/api/controlplane/renew`	`tenant.profile.write`	Renew the active entitlement — online when a Control URL is configured (falling back to a local re-verify if unreachable), otherwise a local re-verify reporting the next due time.
POST	`/api/controlplane/deactivate`	`tenant.profile.write`	Deactivate the active entitlement; the deployment reverts to config-based or unlicensed state. Returns `{ ok: true }`.
GET	`/api/controlplane/telemetry-preview`	`operations.read`	The exact fleet-health payload that would be reported: licensing + health bands only — no content, names, paths, or raw asset counts. Includes `telemetryEnabled` / `wouldSend`.
POST	`/api/controlplane/telemetry`	`tenant.profile.write`	Opt telemetry in/out. Body: `{ enabled: boolean }`. Audited.

Support (`support/routes.ts`)

Consent-based support diagnostics. The bundle is generated inside your deployment and returned for preview only — nothing is sent from this endpoint. Uploading an approved bundle to a support case is a separate, deliberate action in the Account portal.

Method	Path	Capability	Purpose
GET	`/api/support/diagnostics/preview`	`operations.read`	Build and return the exact diagnostic bundle a support upload would contain: product version, health, and non-secret configuration only — no customer content.

MCP server

Your deployment includes an MCP (Model Context Protocol) server so AI agents (Claude, IDE agents) can work with it under the same authorization the UI enforces. It is a thin adapter over the HTTP API above — no separate permission model. Run it inside your deployment:

bun run --cwd packages/server mcp     # stdio transport

The server holds a session for one principal and inherits exactly that person’s capabilities: every tool call is authorized, scope-filtered, and audited by the same code paths as the corresponding endpoint, and a 403 is returned to the agent as a tool error. Configure the identity with FMD_MCP_PRINCIPAL (dev auth) or FMD_MCP_SESSION_COOKIE + FMD_MCP_SESSION_CSRF (a pre-established session).

Tool	Kind	Backing endpoint
`list_taxonomy`	read	`GET /api/governance/taxonomy`
`landscape_summary`	read	`GET /api/landscape`
`list_findings`	read	`GET /api/findings`
`review_queue`	read	`GET /api/review/queue`
`ops_overview`	read	`GET /api/ops/overview`
`ai_usage`	read	`GET /api/governance/ai-usage`
`analyst_question`	read	`POST /api/analyst/query`
`draft_remediation`	propose	`POST /api/actions` (draft only)
`start_scan`	propose	`POST /api/scans` (non-destructive)

Writes are proposal-only by design: an agent can draft a remediation or start a read-only scan, but approving, executing, confirming, or writing labels is deliberately not exposed — those remain human actions in the product.

Permissions manifest — roles, capability grants, and Microsoft Graph permission requirements
Threat model — the security invariants these endpoints enforce
Architecture — where the route modules sit in the system
ADR-0003 — persistence model behind these APIs
ADR-0004 — dev/Entra authentication design

Get started

Run & operate

Security & trust

Reference

Licensing & releases

Conventions

Capability column legend

Authentication model

CSRF

401 / 403 / 404 semantics

Error envelope

Endpoint reference

Health (`routes/health.ts`)

Auth (`identity/auth-routes.ts`)

Governance (`governance/routes.ts`)

Scan (`scan/routes.ts`)

Models (`routes/models.ts`)

Review (`review/routes.ts`)

Analyst (`analyst/routes.ts`)

Actions (`actions/routes.ts`)

Read models (`routes/read-models.ts`)

Admin (`admin/routes.ts`)

Notifications (`notifications/routes.ts`)

Teams (`teams/routes.ts`)

Exchange (`exchange/routes.ts`)

Control plane (`controlplane/routes.ts`)

Support (`support/routes.ts`)

MCP server

​Conventions

​Capability column legend

​Authentication model

​Session cookie

​CSRF

​401 / 403 / 404 semantics

​Error envelope

​Endpoint reference

​Health (routes/health.ts)

​Auth (identity/auth-routes.ts)

​Governance (governance/routes.ts)

​Scan (scan/routes.ts)

​Models (routes/models.ts)

​Review (review/routes.ts)

​Analyst (analyst/routes.ts)

​Actions (actions/routes.ts)

​Read models (routes/read-models.ts)

​Admin (admin/routes.ts)

​Notifications (notifications/routes.ts)

​Teams (teams/routes.ts)

​Exchange (exchange/routes.ts)

​Control plane (controlplane/routes.ts)

​Support (support/routes.ts)

​MCP server

​Related documents

Conventions

Capability column legend

Authentication model

Session cookie

CSRF

401 / 403 / 404 semantics

Error envelope

Endpoint reference

Health (`routes/health.ts`)

Auth (`identity/auth-routes.ts`)

Governance (`governance/routes.ts`)

Scan (`scan/routes.ts`)

Models (`routes/models.ts`)

Review (`review/routes.ts`)

Analyst (`analyst/routes.ts`)

Actions (`actions/routes.ts`)

Read models (`routes/read-models.ts`)

Admin (`admin/routes.ts`)

Notifications (`notifications/routes.ts`)

Teams (`teams/routes.ts`)

Exchange (`exchange/routes.ts`)

Control plane (`controlplane/routes.ts`)

Support (`support/routes.ts`)

MCP server

Related documents