Image Optimization APIs

Category: Security & Operations

Signing, origin protection, private delivery, and production observability.

What should image pipeline observability include?

Short answer: Observe each stage separately: upload, source fetch, transformation, derivative storage, CDN cache, browser selection, and page rendering. Use stable asset and request identifiers, bounded labels, sampled detail, and alerts tied to user impact rather than raw request volume.

An image that looks slow in a browser may be waiting on the HTML, fetched from a remote origin, encoded for the first time, missed at the edge, oversized for its slot, or delayed by rendering. A single endpoint latency metric cannot distinguish those causes.

What should ingestion expose?

Track upload attempts, accepted and rejected bytes, validation duration, processing duration, ready rate, failure reason, retry count, and age of the oldest unfinished asset. Record asset ID and upload intent ID so retries can be connected without creating duplicates.

Monitor dimensions, formats, and pixel counts of accepted sources. A sudden change may signal a new content workflow that exceeds assumptions. Treat rejection categories as product feedback as well as security signals.

The upload pipeline guide defines useful lifecycle states. Dashboards should use the same state vocabulary so operators and application developers discuss one model.

What should source retrieval expose?

For origin-pull systems, record normalized origin name, status, DNS and connection timing when available, time to first byte, response bytes, redirect count, timeout type, and policy rejection. Avoid raw remote URLs if they contain credentials or uncontrolled high-cardinality query strings.

Separate origin failures from transformation failures. A processor cannot fix a slow or unauthorized source. Track the percentage of transformations that required a remote fetch versus a managed original.

Security rejects belong here too. Denied private addresses, disallowed hosts, and invalid redirects should feed alerts described in the remote origin protection guide.

What should transformation expose?

Measure cold transformation rate, queue delay, processing duration, output dimensions, output format, encoded bytes, failure reason, and resource-limit rejection. Aggregate by named preset and bounded dimension bucket rather than full raw transformation strings.

Track unique normalized variants per asset and new variants per minute. These reveal unbounded dimensions or abuse. A sharp increase can precede storage and cost problems even when requests still succeed.

If automatic format or quality is used, record the resulting format and policy tier. Without output facts, an unexpected large response becomes hard to explain.

What should cache and delivery expose?

At each cache layer, capture hit, miss, stale, revalidated, or bypass status; age; response time; response bytes; content type; and region. Distinguish derivative-cache reuse from CDN edge hits if the platform makes both visible.

Monitor cache hit ratio alongside request distribution. A healthy global ratio can hide one region, preset, or route with persistent misses. Track purge requests and completion separately from normal delivery.

The cache key design guide supplies the fields needed to interpret fragmentation. Do not use full signed URLs as metric labels. Extract a stable preset, version, and status while placing detailed URLs only in access-controlled sampled logs.

What should the browser and page expose?

Collect selected candidate, rendered dimensions, intrinsic dimensions, transferred bytes, image timing, LCP attribution, and layout shift involvement for a sample of page views. Segment by page template, component, device class, and connection category.

Use the browser’s currentSrc and resource timing information where cross-origin timing policy permits. The W3C defines Resource Timing for performance data, while Google’s web-vitals library can help attribute Core Web Vitals in field monitoring.

Connect browser observations to delivery policy using a stable asset ID or preset, not a secret token. The payload waste guide explains useful sizing calculations.

Which alerts are actionable?

Alert on sustained error-rate increases, high latency percentiles, old queued work, cold-transform surges, cache-hit collapse, private-origin rejection spikes, and a rise in LCP image load delay. Include a route, region, preset, or error class so responders have a starting point.

Avoid paging on total traffic alone. A successful campaign can look like an incident. Use rates, ratios, saturation, and user-facing thresholds. Pair alerts with a short runbook that identifies relevant logs, a safe test asset, cache checks, and rollback controls.

How do you control cardinality and privacy?

Metrics labels must be bounded. Use known preset, status, format, region, and dimension buckets. Put asset IDs, request IDs, and raw diagnostic context in logs or traces with sampling and retention controls.

Never log signing secrets, full bearer tokens, embedded origin credentials, or sensitive filenames by default. Hash or redact identifiers where business requirements allow. Restrict access to logs that reveal private asset usage.

End-to-end observability is a correlation problem. A stable request context should connect the browser-visible result to edge delivery and backend processing without forcing every detail into one metric. When each stage emits a clear outcome, image incidents become a sequence of testable facts instead of a vague report that pictures are slow.

September 6, 2026
Choose a private image delivery pattern

Short answer: Use an application proxy when every request needs application-level authorization, signed URLs when a time-bounded bearer capability is acceptable, and edge authorization when you need both access checks and CDN delivery. Some transformed derivatives may be safely public even when originals are private, but that must be an explicit policy.

There is no single definition of a private image. A customer invoice scan, a draft campaign asset, a paid publication image, and a profile photo each have different access, sharing, revocation, and caching needs. Start with the threat model and lifecycle, not the delivery feature name.

Pattern 1: proxy every request through the application

The browser requests an application URL with its normal session. The application authorizes the user, retrieves or streams the image, and returns it. This provides immediate business-rule enforcement and can hide storage details completely.

The tradeoff is load. Your application handles image bandwidth and long responses unless a protected acceleration layer is added. Poorly implemented proxies buffer entire files, tie up workers, omit range support, and become a reliability bottleneck.

Use streaming, strict upstream limits, correct content headers, and a cache policy consistent with the data. Do not allow an arbitrary upstream URL parameter or the proxy becomes an SSRF surface. The origin protection guide applies here.

Pattern 2: issue expiring signed URLs

After authenticating the user, the application returns a URL containing a verifiable signature and expiry. The browser retrieves the image directly from the media service or CDN. This offloads transfer and works well when temporary bearer access matches the product.

Anyone who obtains the URL can generally use it until expiry unless the token is bound to another property. Short lifetimes improve revocation but can break long sessions and caching. Long lifetimes improve reliability but extend exposure.

Cloudflare documents this model for serving private images. Cloudinary describes authenticated and private delivery types in its control access documentation. Behavior and cache semantics differ, so test your provider.

The signed image URL guide explains what to sign and where keys belong.

Pattern 3: authorize at the edge

An edge function or CDN authorization feature validates a cookie, token, or application-issued assertion before allowing a cached object to be returned. This can preserve low-latency delivery while applying an access decision on every request.

The cache must not bypass authorization. Validate before cache delivery or use a product feature explicitly designed for protected caching. Avoid varying the stored image by every user identity when the bytes are shared among an authorized group; validate the user and then map to stable content identity.

Edge authorization adds another runtime and deployment surface. Keep token verification narrow, use protected secret storage or asymmetric verification, and define failure behavior if identity services are unavailable.

Pattern 4: keep originals private and publish selected derivatives

A site may hold an original privately while intentionally publishing a watermarked, low-resolution, or approved crop. This works when the derivative itself is not sensitive. It does not protect the derivative merely because the source is private.

Make publication a recorded state transition. Use distinct delivery identifiers or namespaces so a public cache cannot accidentally serve a private variant. Prevent arbitrary transformations from a public derivative back to a larger or unwatermarked result.

How should caching be designed?

Decide whether the response is user-specific, group-shared, or identical for everyone who passes authorization. Set browser and shared-cache directives accordingly. A private cache directive concerns shared cache storage; it does not authenticate the requester.

Separate the authorization token from the content key where the platform safely supports it. Otherwise, unique signatures can fragment the cache. But never remove a token from cache identity if doing so also removes the access check.

Test a warm object with a valid token, expired token, missing token, and a token for another asset. Then repeat from another account and region. Review the image cache key guide before making query exclusions.

What about revocation and logging?

Expiry is not immediate revocation. For urgent removal, rotate an asset version, disable its delivery ID, update the authorization policy, or purge protected caches according to provider capabilities. Document which action reaches which layers.

Log access decisions with asset ID, policy, result, and trusted principal identifier where required. Do not log full bearer tokens. Apply retention and privacy controls to logs because image access can itself reveal sensitive behavior.

Choose the simplest pattern that satisfies the real access model. Public content should stay simple. Sensitive content needs explicit authorization boundaries, cache tests, revocation procedures, and observability that proves the boundary is working.

September 1, 2026
Protect remote image origins from SSRF

Short answer: Do not let a public image URL fetch arbitrary user-supplied destinations. Prefer registered source identifiers, restrict schemes and hosts, resolve and validate addresses, recheck redirects, block private networks, isolate egress, and enforce strict response limits.

An origin-pull image service makes server-side requests on behalf of a caller. Without controls, an attacker may target internal services, cloud metadata endpoints, localhost, administrative interfaces, or large responses. Image decoding does not make the request safe.

Prefer source IDs over arbitrary URLs

The safest public interface accepts an approved asset ID or a path relative to a configured origin. The service looks up the actual base URL and credentials from trusted configuration. Callers cannot choose the scheme, host, port, or network destination.

If a business workflow must import remote URLs, place it behind authentication and an ingestion job. Fetch once, validate, store the result as a managed asset, and serve future derivatives from that controlled source. The upload pipeline describes the validation stages.

Avoid embedding remote credentials in public URLs. Configure origin authentication on the server and scope it to a narrow path.

What should a URL allowlist validate?

Allow only required schemes, normally HTTPS. Parse with a maintained URL library and reject ambiguous or malformed forms. Compare normalized hostnames against an exact allowlist or a carefully defined subdomain rule. Do not use a substring check.

Disallow unexpected ports, user-info fields, IP literals, and fragments. Normalize internationalized domains consistently. Resolve DNS and reject loopback, link-local, private, multicast, and other nonpublic address ranges unless a specifically isolated private origin is part of the design.

OWASP’s SSRF Prevention Cheat Sheet details allowlisting, network controls, and common bypasses. Apply the checks before each connection, not only when configuration is saved.

Why must redirects and DNS be rechecked?

An allowed public URL can redirect to a forbidden internal destination. Either disable redirects or validate every hop with the same policy. Limit the number of hops and do not forward origin credentials across hosts.

DNS answers can change between validation and connection. Resolve through a controlled resolver, validate all returned addresses, and ensure the connection uses an approved result. Rebinding defenses need both application validation and network egress controls.

Cloudflare documents its source-origin allowlist for image transformations. Product protections vary, so do not assume a managed fetcher exactly matches your allowlist requirements.

What network controls provide defense in depth?

Run fetch and decode work in an isolated environment with no route to internal control planes or metadata services. Use outbound firewall rules or a proxy that permits only approved destinations. Separate this worker’s identity from application and infrastructure credentials.

Network controls remain valuable if URL parsing has a bug. Application allowlists remain valuable if network configuration changes. Neither layer should be the only barrier.

Set connection, header, body, and total timeouts. Limit response bytes before buffering, verify the detected media type, cap decompressed pixels and frames, and abort slow streams. A valid public host can still return a decompression bomb or an endless response.

How do signatures help?

A signature can ensure that only a trusted application constructs a remote-fetch request. It does not make the destination safe by itself. The signer must enforce the allowlist and resource policy before issuing the URL, and the image service should still enforce its own limits.

Use the signed URL policy to cover the approved source reference and transformation. Do not sign a base URL while leaving a redirect target or nested source parameter mutable.

What should be logged and alerted?

Log the normalized source ID, approved host, resolved public address, redirect count, response size, content type, timing, and rejection reason. Avoid logging embedded credentials, full signed tokens, or sensitive query strings.

Alert on denied private addresses, repeated malformed hosts, unusual ports, redirect loops, high fetch failure rates, and sudden traffic to a new approved origin. Correlate source fetch logs with transformation requests through a safe request ID.

The image pipeline observability guide describes broader operational signals. SSRF defenses should appear in the same dashboards and incident playbooks as reliability failures because attackers often look like unusual origin errors first.

Remote fetching is a privileged server capability. Expose a controlled asset vocabulary to normal callers, isolate the component that performs network access, and make every rejected destination visible enough to investigate.

August 27, 2026
When should you use signed image URLs?

Short answer: Sign URLs when the server must prove that a caller may access an asset or request a restricted transformation. Keep the signing key on trusted infrastructure, cover every policy-relevant field, use bounded expiry where appropriate, and separate access proof from cache identity.

Public marketing images usually do not need per-request signatures. Private customer documents, embargoed media, paid content, and expensive transformation capabilities often do. The important question is what the signature authorizes.

Delivery authorization or transformation authorization?

Delivery authorization answers whether a requester may receive an asset. A token may include asset identity, expiry, and perhaps a user or policy scope. The server validates it before returning bytes.

Transformation authorization answers whether a requested derivative is allowed. A public source might permit a few safe presets but require a signature for arbitrary overlays, very large output, or remote fetches. This protects compute and prevents unauthorized manipulation.

The two concerns can share a signature scheme but should remain explicit. A URL that proves access to one original should not automatically authorize every possible transformation of it.

Cloudinary documents signed delivery and transformations in its authentication signatures guide. Cloudflare documents signed URLs for Images in its private images guide. The algorithms and token fields differ, so follow the provider’s canonical implementation.

What must the signature cover?

Cover the asset identifier and version, normalized transformation or preset, expiry, and any policy scope that the verifier enforces. If width or crop can be changed without invalidating the signature, the token does not control those operations.

Canonicalize before signing. Parameter order, encoding, default omission, and numeric formatting must be deterministic on both sides. Use one typed URL builder rather than reimplementing signature strings in multiple clients.

Do not invent a cryptographic format when the provider supplies one. Use maintained libraries where available, compare signatures in constant time on systems you operate, and rotate keys through a documented process.

Where should signing happen?

Only on a trusted server, edge worker with protected secret storage, or another controlled backend. Never ship the signing secret in browser JavaScript, a mobile application, a public repository, or page markup.

The browser can request a short-lived URL from your application after authentication. The application checks business authorization and returns the minimum capability required. For pages rendered on the server, it can generate signed URLs during rendering.

Avoid exposing administrative API credentials when only a delivery signature is needed. Use the narrowest credential and isolate image signing from unrelated account operations.

How long should a signed URL live?

Choose expiry from the sensitivity of the content, expected viewing session, CDN caching model, and failure tolerance. A very short expiry can break slow clients, saved pages, retries, and caches. A very long expiry behaves more like a revocable secret link.

Expiry limits future use but does not retract bytes already downloaded. For highly sensitive images, combine short-lived authorization with application controls, logging, and a realistic understanding that the client can copy visible content.

Clock skew should be considered. Log the verifier’s rejection reason internally without revealing signing details to callers. Provide enough margin for normal request delay.

How do signatures interact with caching?

If each signed URL contains a unique token and the CDN includes it in the cache key, identical bytes can fragment across many entries. Some systems validate the token and then cache by stable content identity. Others require deliberate cache-key configuration.

Never ignore a security parameter at the cache without ensuring authorization still runs on every protected request. A cached private response must not become publicly retrievable merely because the token was removed from identity.

The cache key design guide explains content identity versus access proof. Test the actual sequence with valid, invalid, expired, and missing tokens, including a warm cache.

What should you monitor?

Track signature validation failures by reason, requested asset or policy class, credential ID, and rate. Avoid logging full tokens. Alert on unusual failure bursts, high-cardinality transformations, repeated requests near expiry, and use of a retired key.

Keep an audit trail for signing operations involving sensitive assets. Record which trusted service issued the capability and the policy applied. Do not record more personal data than necessary.

Pair signing with the private image delivery patterns appropriate to your threat model. A signature is one control within an access architecture, not a declaration that the entire path is private.

Use signed URLs when they express a specific, enforceable capability. Scope them narrowly, generate them only in trusted code, test cache behavior, and make failure visible to operators.

August 19, 2026