Skip to content
System Design Lab
Microservice Patterns

Valet Key

Give clients a short-lived, narrowly scoped token to read or write one resource directly in storage, so large transfers bypass your servers without handing out real credentials.

Beginner 4 min read· Updated 2026-11-18

What you will learn

  • Explain why proxying uploads and downloads through an API wastes capacity.
  • Issue scoped, expiring signed URLs or SAS tokens.
  • Limit what a valet key can do: object, operation, size, time.
  • Validate what arrives after a direct upload.

Overview

A valet key lets a parking attendant drive your car, but not open the boot or the glovebox, and it is handed back when you leave. You do not give them your house keys.

Uploading or downloading big files through your API ties up workers, memory and bandwidth for no benefit — the API only copies bytes. With a valet key, the API checks that the user may perform the action and returns a signed URL (S3 presigned URL, Azure SAS token, GCS signed URL) that allows exactly one operation on one object for a few minutes. The client then talks to storage directly.

Run it

Creators upload 20 MB videos while shoppers browse. Compare API workers busy and Browse requests failed when uploads go through the API (A) and when the API only signs URLs (B).

Loading simulation…

Issue a scoped upload URL

S3 presigned PUT: one key, one content type, five minutes
@PostMapping("/videos/upload-url")
UploadUrl uploadUrl(@AuthenticationPrincipal User user, @RequestBody @Valid UploadRequest req) {
    if (req.sizeBytes() > 500_000_000) throw new PayloadTooLargeException();
    String key = "uploads/" + user.id() + "/" + UUID.randomUUID() + ".mp4";      // server chooses the name
    PutObjectRequest put = PutObjectRequest.builder().bucket("videos").key(key)
        .contentType("video/mp4").contentLength(req.sizeBytes()).build();
    PresignedPutObjectRequest signed = presigner.presignPutObject(b -> b.signatureDuration(Duration.ofMinutes(5)).putObjectRequest(put));
    videos.registerPending(user.id(), key);
    return new UploadUrl(signed.url().toString(), key);
}
  • Scope tightly: one object (server-generated name), one verb, required content type and length.
  • Keep it short-lived: minutes, not days; anyone who sees the URL can use it until it expires.
  • Validate afterwards: an upload event triggers scanning and verification before the file is used.
  • Downloads too: signed GET URLs (or CDN signed URLs) serve private files without proxying.

Trade-offs

BenefitsCosts
ScalabilityBulk transfer moves to storage built for it; API stays small.Two steps for the client (get URL, then upload).
SecurityLeast privilege, time-limited access, no long-lived credentials on clients.A leaked URL works until it expires; validation moves after the upload.
ControlStorage enforces size, type and expiry.Progress, retries and resumable uploads must be handled client-side.

Production considerations

  • Configure CORS on the bucket for browser uploads, limited to your origins.
  • Use multipart / resumable uploads for large files and mobile networks.
  • Expire orphaned pending uploads with lifecycle rules.
  • Combine with claim check when the uploaded object then flows through messaging.

Further reading

Related topics