Reading grants

When the subject approves and fulfills an item, it becomes a grant you can view. Nothing is ever downloadable — you open a hosted, watermarked, view-only session.

List / fetch grants

GET /partner/v1/grants · GET /partner/v1/grants/:id

Scope: grants:read.

{
  "grantId": "…",
  "requestId": "…",
  "requestItemId": "…",
  "state": "active",
  "document": {
    "name": "passport.pdf",
    "syntheticId": "LK-8F3K2A9C",
    "classification": "passport",
    "sensitivity": "restricted",
    "pageCount": 2
  },
  "viewsUsed": 1,
  "maxViews": 5,
  "expiresAt": 1767225600000,
  "viewerUrl": "https://…/viewer/…",
  "createdAt": 1767140000000
}

viewerUrl opens the hosted watermarked viewer in the console — the simplest way for a human reviewer to look at the document.

Mint a watermarked viewing session

POST /partner/v1/grants/:id/sessions

Scope: grants:read. Mints a fresh watermarked viewing session and consumes one view (recorded in the owner's audit trail):

{
  "sessionId": "…",
  "expiresAt": 1767141800000,
  "document": {
    "name": "passport.pdf",
    "syntheticId": "LK-8F3K2A9C",
    "sensitivity": "restricted",
    "pageCount": 2
  },
  "watermarkLines": ["Shared via Lockey", "Acme HR · employment_verification", "…"],
  "pages": [ /* page image URLs, watermark burned into the pixels */ ]
}

The watermark is burned into the page images server-side — viewer name, purpose, timestamp, session id, synthetic id, and sensitivity. There is no clean copy to fetch and no overlay to strip.

A session consumes a view

Each minted session counts against the grant's maxViews and is logged. Mint one per actual review, not per page render — render all pages from the single pages array the call returns.

When a grant can't be viewed

If the grant is revoked, paused, or over its view cap:

409 { "error": "grant_not_viewable" }

The owner's billing/state is never disclosed in that response — you only learn that it isn't currently viewable, not why.

Next: Rate limits →