Consent, revocation, and deletion

Consent receipts

When a patient shares with your app, FinchNode writes a consent receipt. It records the categories, the source, how long the share lasts, and its status. GET /consents/{receiptId} returns one, and every snapshot lists the receipts behind it.

A patient who shares from two health systems has a receipt for each.

What a read can return

Response	Means	Do this
403 app_scope_exceeded	The category isn't on your application's list.	Add it in the console, or stop asking for it.
403 consent_scope_exceeded	Your app may read it, but this patient didn't share it.	Read only shared categories. A new session can ask for more.
410 consent_inactive	No active receipt is left: the patient revoked sharing, or it expired.	Stop reading this subject and apply your retention policy.
404 not_found	The subject is gone, for example after a deletion request.	Stop reading and make sure you've deleted your copy.

Record and change-feed reads keep returning 410 once consent is inactive. Expiry is enforced at read time, even before the expiry webhook arrives.

Handle revocation and expiry

A patient can revoke sharing from their FinchNode account at any time. A share also ends when its durationDays runs out. With a webhook URL set, you hear about both:

Event	data includes
consent.revoked	receiptId, action, status, revokedAt
consent.expired	receiptId, action, status, expiredAt

When one receipt ends but another is still active, reads keep working, minus that source. Its records drop out of reads and the change feed without delete entries. To remove them:

1. Read GET /consents/{receiptId} for the receipt that ended.
2. Take its source and categories.
3. Delete the records you hold with that source in those categories.

Handle a deletion request

When a patient asks FinchNode to delete all their data, every app they shared with gets deletion.requested for that subject. FinchNode then revokes their receipts and deletes its own copy, so the subject starts returning 404 not_found and no delete changes follow.

Your copy is now the only one. Delete what you hold for that subject, following your retention policy and the law that applies to you.

Keep a record of what you did

Log the event ID, the categories, and how many records you removed. Don't log record IDs or contents. See Handling patient data.