RTFC API

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 ──(provisioner token)──> POST /v1/provision/user
                                        └─> returns a per-user token
your backend ──(that user's token)───> everything else

1. Create an account when a user signs up

bash
curl -sX POST $RTFC/provision/user \
  -H "X-Auth-Token: $PROVISIONER_TOKEN" \
  -H 'Content-Type: application/json' -d '{}'
json
{"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

bash
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 public video should not pay twice. If a public analysis already exists, grant access to it instead of ingesting again:

bash
curl -sX POST $RTFC/media/youtube/$VIDEO_ID/claim-access -H "X-Auth-Token: $USER_TOKEN"
# {"debate_id": "…", "granted": true}   404 = nobody has analysed it yet

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