Valet Key Pattern

💻 Client

The user's device that wants to upload a file — like a profile photo (avatar-1.png) or a PDF.

🖥️ Upload Server

A backend Web Server that generates secure signed URLs for specific files. It doesn't receive the file data itself — it only issues permission tokens.

☁️ Cloud Storage

An object storage bucket (like AWS S3 or Google Cloud Storage) that accepts direct uploads from clients using Valet Keys / Signed URLs. Files land here without ever passing through the server.

Flow overview:

Client → Server: "I want to upload avatar-1.png"
Server → Client: "Here's a signed URL with a 15-min token"
Client → Storage: Upload file directly using the signed URL
Storage → Client: "Upload success! File saved."

When users upload files, the naive approach is to send them to your backend server first:

Client → Server → Storage

This creates a massive problem at scale:

- A 50MB video upload occupies a server thread for seconds.

- With 1,000 concurrent uploads, your server runs out of memory.

- Your server's bandwidth gets saturated — other requests slow down.

The Valet Key Pattern Solves This

Named after the valet parking model: *you give the valet your car key, but only with limited permissions* (they can park it — not sell it). See Valet Key / Signed URL.

The idea:

The server never touches the file bytes. Your backend handles only lightweight token generation!

In the simulator, you'll see 4 distinct steps (frames):

Step 1 — Request Permission

Client → Server: *"I want to upload avatar-1.png to the media-uploads bucket."*

Step 2 — Receive Signed URL *(amber/yellow packet = response)*

Server → Client: Returns a pre-signed URL containing:

- The bucket name

- The file name

- An expiry timestamp (e.g., valid for 15 minutes)

- A cryptographic signature proving the server authorized it

Step 3 — Direct Upload

Client → Storage: Sends the file bytes directly with the signed URL as a token. The server is completely bypassed.

Step 4 — Upload Confirmation *(amber packet = response)*

Storage → Client: "Upload successful. File stored in media-uploads/avatar-1.png"

Watch the packet colors — purple = request going forward, amber/yellow = response going backward.

Interactive Checkpoints

Implement the Valet Key pattern from scratch:

🛠️ Step-by-Step

After completing, notice that the server only appeared in steps 1–2. The actual file data (step 3) bypassed it completely. That's the valet key pattern!

🎉 You've Finished All Guides!

Ready to design any system you can imagine? Open the Sandbox and experiment freely. Some ideas to try:

- Build a full stack with API Gateway + Load Balancer + Cache + DB

- Add a CDN in front of Storage for faster global delivery

- Test what happens when you misconfigure routing rules