Revoking document access via API: how it actually works

Revocation is the control that makes people do a double-take. Everyone understands protecting a document before it goes out; ending access to a document someone downloaded three weeks ago sounds like it shouldn't be possible. It is — but only because of a specific architectural choice, and understanding that choice tells you exactly what revocation can and cannot do for you. This is a technical walkthrough of revoking document access with the MyPass DRM API: the mechanism, the granularity, the timing, and the events worth wiring to it.

Why revocation works on delivered documents

A protected document is not a locked file with a key inside it. Opening one triggers a policy check against the service: is this reader still authorized, on an authorized device, before expiry, within the open limit? The document renders only when the answers come back yes. Revocation, then, isn't reaching into someone's laptop and deleting a file — it's changing the answer the next check gets. The copy on their disk becomes inert because the thing that made it readable, a passing policy check, no longer passes.

This is why revocation has one honest boundary worth stating up front: it takes effect at the next open. A document a reader currently has on screen stays on screen for that session; a reader inside an offline-access window keeps access until the window ends. What revocation guarantees is that access does not survive into the future — not that a view in progress vanishes mid-sentence.

The call, and what you can aim it at

The endpoint is small: POST /api/v1/activations/{id}/revoke. The interesting part is what an activation is — the unit that ties a specific reader and a specific authorized device to a document. That gives you granularity most teams don't expect:

• Revoke one device. A reader reports a stolen laptop; you end that device's activation and their phone and desktop carry on unaffected.
• Revoke a reader. End every activation a person holds on a document — the offboarding case.
• Revoke around a document. A superseded price list, a report released with an error, a deal that fell through: end the activations on that document and distribute the corrected version as fresh access.

Each revocation lands in the access record alongside the opens it prevented — GET /api/v1/audit will show the denials — which turns "did we actually cut access?" from a hope into a query.

Events worth wiring to revocation

Manual revocation is for incidents. The durable value comes from wiring it to the events in your systems that already mean "this access should end":

• Offboarding. HR marks a departure; your handler revokes their activations across internal documents the same hour. This is the single highest-value hook for enterprises.
• Subscription and membership lapse. The billing system's cancellation event is the revocation trigger for paid content — though for predictable end dates, expiry set at grant time is cleaner: it needs no event at all.
• Enrollment end. Course completion or withdrawal ends courseware access; the LMS integration guide shows where this hook lives.
• Anomaly response. If your monitoring flags something — a credential clearly being shared, a partner relationship terminated — revocation gives the response team a lever that works after delivery.

A good rule from practice: expiry for the endings you can predict, revocation for the ones you can't. Systems that lean on revocation for predictable endings accumulate event-handler complexity that a date on the policy would have handled for free.

Testing it honestly

Before you trust the loop, close it yourself: protect a test document, grant a test reader, open it, revoke, open again. The second open should be a denial — and both events should be in the audit log. That five-minute exercise, on the free tier where the full API is available, tells you more than any documentation page. For the wider automation picture around revocation — grant-and-revoke symmetry, protecting at the point of creation — see the API document-security guide.