Share private media with signed URLs
Goal: store media that must never be public (invoices, user uploads, internal screenshots) and let only the right people view it, through links that expire on their own. How signing works is covered in Private media; this guide wires it into an app.
1. Upload privately
Set visibility=private on upload. The response's url is already signed and works until signed_expires; store the id, not the URL.
curl -X POST https://api.pixelvault.dev/v1/images \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-F "file=@invoice-scan.png" \
-F "visibility=private" \
-F "sign_expires_in=600"
→ { "data": { "id": "img_abc123", "visibility": "private",
"url": "https://img.pixelvault.dev/…?token=…&expires=1795449600",
"signed_expires": 1795449600 } } Video and audio use X-PixelVault-Visibility: private; see the video and audio guides.
2. Mint links on demand
Put a route in front of the media that checks your own authorization, then calls POST /v1/images/:id/sign-url and redirects. Your API key stays on the server, and every viewer gets a short-lived link:
// server.mjs: node server.mjs, then open http://localhost:3000/invoice/img_abc123
// Redirects an authorized viewer to a fresh 5-minute link; caches links until shortly before expiry.
import { createServer } from "node:http";
const API = "https://api.pixelvault.dev/v1";
const cache = new Map(); // image id -> { url, expires }
async function signedUrl(id) {
const hit = cache.get(id);
if (hit && hit.expires - Date.now() / 1000 > 60) return hit.url;
const res = await fetch(`${API}/images/${id}/sign-url`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PIXELVAULT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ expires_in: 300 }),
});
if (!res.ok) throw new Error(`sign-url failed: ${res.status}`);
const { data } = await res.json();
cache.set(id, data);
return data.url;
}
createServer(async (req, res) => {
const match = req.url.match(/^\/invoice\/(img_[A-Za-z0-9]+)$/);
// Replace with your own session check: only the invoice's owner may see it.
if (!match) return res.writeHead(404).end();
try {
res.writeHead(302, { Location: await signedUrl(match[1]), "Cache-Control": "no-store" }).end();
} catch {
res.writeHead(502).end();
}
}).listen(3000); Caching a link until shortly before it expires keeps sign-url calls (and the per-minute rate limit) low. For video and audio use /v1/videos/:id/sign-url or /v1/audio/:id/sign-url, which return the original plus every existing artifact (poster, captions, transcripts) under one expiry.
3. Pick a link lifetime
- Page views: minutes (
expires_in: 300), minted per request. - Emails and PR comments: hours to days; the link must outlive the time to click.
- Agents and webhooks: payloads for private media carry 7-day links and a
refresh_url.
The range is 60 seconds to 30 days. A link can't be revoked early; deleting the asset revokes all of them.
Next steps
- Private media & signed URLs: the concept, limits, and errors.
- Private CI screenshots.
- Private images for AI agents.