REFRACT Delivery API Reference

All REFRACT Delivery endpoints are hosted on the Dispatcher Azure Function. Initiator routes require a valid Entra ID JWT. Recipient portal routes use a delivery access token issued at session creation, sent by the portal as Authorization: Bearer <token>. A token in the URL (?t=) is refused with 401 LINK_TOKEN_IN_URL. The recipient's link carries a link reference (/d/<linkReference>), not the token: the portal resolves the reference and sends the token to the Dispatcher on the recipient's behalf.

Create Delivery Session

POST /api/delivery

Creates one or more delivery sessions (one per recipient) for a rendered document.

Auth: Entra ID JWT. A signed-in user needs the Lifecycle.Reader role; an app-only token needs only the Render.Access application permission. Without it, 403 with code ROLE_MISSING naming the missing role.

Request body:

{
  "correlationId": "rnd-00123",
  "documentId": "DOC-456",
  "documentName": "Invoice #INV-2026-001.pdf",
  "pdfBlobPath": "generated-documents/invoice/2026/05/rnd-00123.pdf",
  "mode": "secure-email",
  "recipients": [
    {
      "email": "vendor@contoso.com",
      "name": "Vendor Contact",
      "role": "recipient"
    }
  ],
  "requesterOrg": "Contoso Ltd",
  "message": "Please find your document attached. This link expires in 7 days.",
  "expiresInHours": 168,
  "requireOtp": false
}

Response 201:

{
  "sessions": [
    {
      "deliveryId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
      "recipient": "vendor@contoso.com",
      "portalUrl": "https://portal.refractplatform.com/d/<linkReference>"
    }
  ],
  "expiresAt": "2026-06-16T12:00:00.000Z",
  "emailsSent": 1
}

Query Delivery Sessions

GET /api/delivery-sessions?correlationId={correlationId}

Returns all delivery sessions for a given document correlation ID.

Auth: Entra ID JWT with the Lifecycle.Reader role (the response includes recipient addresses). Without it, 403 with code ROLE_MISSING.

Response 200:

{
  "sessions": [
    {
      "id": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
      "mode": "secure-email",
      "recipient": "vendor@contoso.com",
      "recipientName": "Vendor Contact",
      "recipientRole": "recipient",
      "sentAt": "2026-06-09T12:00:00.000Z",
      "accessExpires": "2026-06-16T12:00:00.000Z",
      "openedAt": "2026-06-10T09:14:22.000Z",
      "lastAccessedAt": "2026-06-10T09:15:01.000Z",
      "viewCount": 2,
      "state": "opened"
    }
  ]
}

Each session entry carries id, mode, recipient, recipientName, recipientRole, sentAt, accessExpires, openedAt, lastAccessedAt, viewCount, and state. There is no createdAt, per-item correlationId (it is the query filter, not a field on each session), documentName, or downloadedAt in this response.

Get Delivery Session (Portal)

GET /api/delivery/{deliveryId}

Validates the recipient's access token and returns session metadata for the delivery portal UI, including the document name. Called by the portal when the recipient opens their link.

Auth: Delivery access token (Authorization: Bearer <token>, sent by the portal)

Returns 410 Gone if the session is expired or revoked.

Record Access Event

POST /api/delivery/{deliveryId}/access

Records that the recipient accessed the document. Called by the delivery portal when the recipient opens the document view. The request body, if any, is ignored - the route does not read it, so any eventType or ip field sent has no effect.

Auth: Delivery access token

Sets the session state to opened, records openedAt/lastAccessedAt, and increments viewCount. Writes a DELIVERY_DOCUMENT_ACCESSED audit event carrying the delivery ID and the updated view count.

Response 200: { "ok": true }

Send OTP

POST /api/delivery/{deliveryId}/otp/send

Sends a one-time passcode to the recipient's email address. Only valid when requireOtp: true was set at session creation.

Auth: Delivery access token

Returns 400 if OTP is not required for this session or has already been verified.

Response 200: { "ok": true }

Verify OTP

POST /api/delivery/{deliveryId}/otp/verify

Verifies the one-time passcode entered by the recipient.

Auth: Delivery access token

Request body:

{ "otp": "483921" }

Response 200:

{ "ok": true, "verified": true }

Returns 400 with details if the code is incorrect or expired.

Revoke Delivery Session

POST /api/delivery/{deliveryId}/revoke

Immediately revokes a delivery session. Any subsequent recipient access attempt returns 410 Gone. Revoking a session does not write an audit event.

Auth: Entra ID JWT (initiator - must be same tenant as session creator)

Response 200:

{ "deliveryId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c", "state": "revoked" }

The Delivery Access Token

The delivery access token is an HMAC-SHA256 value computed from the delivery ID and tenant ID. It is not a JWT and carries no embedded claims or expiry - access is gated entirely by the session's own accessExpires/state in Table Storage, checked on every route above. It travels in the Authorization header between the portal and the Dispatcher, not in the emailed link.