Building for your own users#

If your product has end users of its own, do not put all their work under one RTFC account. Give each of them their own.

Why#

debates.created_by is what scopes access. One account for everyone means every debate is visible to every one of your users through your own API surface, and one leaked key exposes all of them. Separate accounts mean isolation is enforced by RTFC, not by your filtering code being correct on every read.

It also makes deletion honest: when a user asks you to erase their data, deleting their RTFC account cascades their debates, claims and panels. You do not have to prove you found every row.

The pattern#

Your backend holds ONE provision-scoped token. It uses that only to create and delete accounts - it cannot read anybody's debates, which is the point: if it leaks, the damage is unwanted accounts, not a data breach.

your backend --(provision token)--> POST /v1/provision/user
                                       └─> returns a user token
your backend --(user token)-------> all other requests

1. Create an account when a user signs up#

curl -sX POST $RTFC/provision/user \
  -H "X-Auth-Token: $PROVISIONER_TOKEN" \
  -H 'Content-Type: application/json' -d '{}'

{"user_id": "8b75…", "username": "esploro_YmpY8i9CFHE", "token": "rtfc_…"}

Store token encrypted, keyed by your own user id. RTFC never learns who your user is - the username is opaque and you send no personal data.

The token is shown once. If you lose it, POST /v1/provision/user/{id}/tokens mints a fresh one.

2. Act as that user#

Every subsequent call for that user uses their token, not the provisioner's. Isolation, quota and billing all follow from it.

3. Delete on request#

curl -sX DELETE $RTFC/provision/user/$USER_ID -H "X-Auth-Token: $PROVISIONER_TOKEN"

Revokes their tokens, tears down any running session, and deletes their debates - except content genuinely shared with other users, which is preserved (see Shared claims).

Sharing between your users#

Two of your users watching the same video each get their own analysis. The second one is fast and costs no transcription: the earlier transcript and speaker names of a public video are reused, and detection and verification run fresh. Only an analysis RTFC has declared shared can be joined instead of analysed again:

curl -sX POST $RTFC/media/youtube/$VIDEO_ID/claim-access -H "X-Auth-Token: $USER_TOKEN"
# {"debate_id": "…", "granted": true}   404 = no shared analysis of this video

The second user now reads the existing debate through the ordinary endpoints, at no research cost.

Analysis visibility and editing#

Analyses default to visibility: private. Owners and editors can share with specific people (people) or the owner’s current team (team). Team membership is live: joiners gain read access and leavers lose it. Owner-managed recipients must be active human users in the owner’s organisation. Team access is read-only unless an individual edit grant applies. Existing independent admin and digest grants remain effective when owner sharing changes. Debate list and detail responses include owner_name, visibility and my_role (owner, editor, reader). Organisation administrators (the existing page:organisation-sources permission) can read and edit analyses owned by their client; platform administrators retain instance-wide authority. Owners and editors can change sharing, correct analysis metadata and speaker attribution, and control research, ingest and sessions. Readers cannot make these changes; private feedback and personal favourites remain available. Deleting an analysis remains restricted to its owner or a platform administrator. The dashboard sharing endpoints are internal and are not published in the public OpenAPI schema.

Organisation source policies#

The debate owner’s organisation can complete the global source catalogue with trust overrides, additional categories and never-cite rules. Organisation administrators manage these policies in the dashboard; the management endpoints are internal. Global blocks always apply. Private research uses an immutable policy snapshot recorded as trust_table_version on each panel. display_trust_table_version identifies the organisation policy used when presenting a result. Shared research remains global and is re-weighted and filtered for each organisation when read, with a separate targeted retrieval for organisation-only trusted domains and domains whose trust it raises above the global catalogue. Mapped pages are read first; missing domains receive a restricted free-engine search. Only that organisation’s cached verdict and method panels can use the extra admitted evidence; a cross-organisation debate access grant exposes canonical answers, not its owner’s private enrichment. Retrieval and synthesis usage is billed to the affected occurrence owner. This also applies to the single claim_verdict and its best alias, including adjudicated and operator answers, in REST and SSE. When a blocked source supports an answer, an asynchronous organisation-scoped synthesis uses admitted evidence without blocked sources. Until ready, claim_verdict and best are null (show “Verification in progress”); affected method panels have verdict: pending. The new answer carries organisation_evidence_filtered: true and organisation_verdict_status: ready. With no remaining evidence it is explained UNVERIFIABLE. Cache revisions include the organisation policy and research; unblocking restores the canonical answer. Canonical research and other organisations remain unchanged. Removed URLs, attempts and costs are available to the organisation administrator through the internal verdict audit. Specify debate_id to select the debate owner’s policy.

organisation_verdict_status: pending → ready

trust_table_version → display_trust_table_version

Console person catalogue#

Any human console user may create a person through POST /v1/candidates or when adding a new speaker to a debate. Only that person’s creator or an admin may edit, delete, merge, re-sync to FaktoLumo, or dismiss duplicate suggestions. Merging and dismissing require ownership of both persons. Persons without a recorded creator can only be changed by admins. Candidate list and search responses include created_by (a user UUID or null) and can_edit. Usage counts and debate/claim details remain scoped to accessible debates. Political party writes remain admin-only; users may select an existing party for their person.

Monitoring recipients#

Dashboard monitoring recipients must be verified active human accounts in the caller’s client and team. Group creation and edits validate membership server-side; delivery and free debate-access reconciliation recheck current membership. Subscription pause preserves configuration and stops collection/automatic analysis for that subscriber. Backfill estimates shown in the dashboard use media hours only, derived from discovered video durations; existing usage attribution and confirmation remain unchanged. A monitoring group can switch off weekdays (skip_weekdays, bitmask Monday=1 to Sunday=64, 0 = every day): on those days its subscriptions' new videos are not analysed automatically and no digest is sent.