Choose account access or a secure link
Account recipients provide an identity-bound delivery path using the recipient public key. Secure links are bearer access while active and are better for guests or one-time handoffs. A single service-owned upload can be provisioned for either pattern when the client supplies the correct encrypted key envelope.
- Account access: look up the existing user and wrap the payload key to that recipient public key.
- Secure link: encrypt the payload key for link-held unlock material and set an expiration and download limit.
- Use the smallest recipient set and shortest practical access window for the business task.
Provision grants in one signed operation
Use POST /api/shares with shares:create for one recipient grant, or POST /api/service/share-provisions to provision account recipients and secure links together after one completed service-owned upload. The response returns share records and any newly created link tokens once; the integration is responsible for delivering each full link through an appropriate channel.
POST /api/shares # one grant
POST /api/service/share-provisions # multiple account and link grants
{
"uploadId": "upload_id",
"accountRecipients": [{ "recipientEmail": "recipient@example.com", "keyEnvelope": "encrypted_key" }],
"secureLinks": [{ "keyEnvelope": "encrypted_link_key", "maxDownloads": 1 }]
}Keep key wrapping in the trusted client
For account sharing, call the signed user lookup endpoint, validate the returned recipient key version, and wrap the payload key locally. For a secure link, generate the link unlock material locally. The API needs the encrypted envelope and delivery metadata; it should not be asked to return a plaintext payload key.
GET /api/users/lookup?email=recipient%40example.com
POST /api/service/share-provisions
# Keep the raw payload key and URL-fragment unlock material out of API logs.Revoke future service-mediated access
Use shares:revoke on POST /api/shares/:id/revoke to stop future opens through ZipPigeon. Revocation and expiration do not erase a plaintext copy that a recipient already downloaded, so the workflow should make the access window, download limit, and recipient responsibilities clear before delivery.
- Track the share ID separately from any bearer link token.
- Revoke by share ID from the trusted service, never by scraping a public link page.
- Treat download counts as service events, not proof that every downstream plaintext copy was deleted.
Benefits and use cases
Share lifecycle APIs let a business system deliver the same encrypted package through different recipient paths while retaining explicit expiration and revocation controls. Common uses include closing-document delivery, customer report distribution, vendor evidence exchange, payroll or HR handoffs, and support bundles sent to a named responder.
- CRM or case system: provision a client grant when a case reaches an approved state.
- One-time external handoff: create a single-download link and deliver it outside shared logs.
- Offboarding: revoke outstanding service-mediated grants when the underlying engagement ends.
Audit the lifecycle, not just creation
Record the business reference, upload ID, share ID, recipient mode, expiration, and revocation decision in the calling system without copying secrets. Pair those records with ZipPigeon audit events and proof packets when a counterparty needs evidence about the handoff timeline.
POST /api/shares/:id/revoke # shares:revoke
GET /api/shares # uploads:read
# Export proof from the owning workspace when evidence is required.