Lesson 29 of 30

BYO API Key Patterns

Q: Design a system that lets users optionally bring their own AI provider API key, falling back to it when the platform's shared key runs out of quota. What are the key pieces, and what would you be most careful about?

A strong answer covers: Describes a fallback ladder: try the platform key first (while it has quota), fall back to the user's own key if provided, and throw a distinct error if neither is available; Names the two real reasons for BYO key support: capping the app's own AI cost exposure, and giving power users access to their own quota/preferred provider; States the core security constraint clearly: a user's own key must never be readable by another user or an unauthorized code path — stored server-side, encrypted at rest, never exposed to a client; Recognizes that encryption at rest alone isn't sufficient — the access-control path that decides who can trigger decryption also has to be correct.

Letting users bring their own API key caps an app's AI bill at something other than "however much every user decides to use" — but it also means the app is now responsible for storing someone else's credential safely.

12 min read

Check your understanding

Every option explains itself — why the right one is right, and why each wrong one is wrong. Miss one and it comes back later on a spaced-repetition schedule.

Question 1 of 3

In a platform-key-first, BYO-key-fallback pattern, what should happen if the platform key is out of quota and the user has never connected their own key?

Throw a distinct error indicating no provider is available, so the user knows they need to connect a keySilently retry the platform key repeatedly until quota resetsAutomatically generate a temporary API key for the user without their involvement

Stuck? Ask the AI tutor

Hints without spoilers, and a plain explanation of why a wrong answer was wrong — answered only from this lesson. Free account, no card.

Interview questions on BYO API Key Patterns

What interviewers actually ask about this, and what a strong answer has to cover.

Design a system that lets users optionally bring their own AI provider API key, falling back to it when the platform's shared key runs out of quota. What are the key pieces, and what would you be most careful about?

A strong answer covers

Describes a fallback ladder: try the platform key first (while it has quota), fall back to the user's own key if provided, and throw a distinct error if neither is available
Names the two real reasons for BYO key support: capping the app's own AI cost exposure, and giving power users access to their own quota/preferred provider
States the core security constraint clearly: a user's own key must never be readable by another user or an unauthorized code path — stored server-side, encrypted at rest, never exposed to a client
Recognizes that encryption at rest alone isn't sufficient — the access-control path that decides who can trigger decryption also has to be correct

Likely follow-ups

Encryption at rest is in place, but there's a bug in the authorization check that lets one user's request decrypt another user's key. Is the data still protected? Why or why not?
Would you store the key using a database-native vault feature or encrypt it yourself in application code? Argue for a choice, and name a real cost of the option you didn't pick.

The plain-language idea

BYO (bring your own) API key means letting a user supply their own provider API key instead of, or in addition to, using AI capacity the app itself pays for. Two real reasons an app reaches for this:

Cost containment. If every user's AI usage is billed to the app's own platform key with no ceiling, a single heavy user (or a bug that loops) can absorb a large, unpredictable amount of cost. A BYO option, or a fallback to it, caps how much of that risk the app itself carries.
Power-user access. Some users already have their own provider account, possibly with a different model, higher quota, or preferred provider than what the app offers by default — letting them use it is a real feature, not just a cost-shifting trick.

The pattern that actually works in production is a fallback ladder, not a binary choice: try the platform's own key first; if that key is out of quota, fall back to the user's own key if they've provided one; if neither is available, tell the user clearly that they need to connect a provider. This keeps the default experience free/seamless for most users while giving the app a safety valve instead of just failing outright when platform quota runs out.

The security point that actually matters here, more than the mechanics: a user's own API key must never be readable by any other user, or by any code path that isn't authorized to use it. It's a real credential — whoever holds it can spend real money on that person's account — so it belongs in the same category as a password: stored server-side, encrypted at rest, never placed anywhere a client or another user's session could read it back out.

See it in a real thing: this app's own key-resolution ladder

// lib/ai/provider/resolveKey.ts
export function resolveProviderConfig(deps: KeyResolutionDeps): ProviderConfig {
  if (deps.platformQuotaOk()) {
    const platform = deps.platformConfig();
    if (platform) return platform;
  }
  const user = deps.userConfig();
  if (user) return user;
  throw new NeedsUserKeyError();
}

This is the fallback ladder made concrete: platform key first (while it has quota), the user's own key second, and a distinct, explicit error (NeedsUserKeyError) if neither is available — rather than a silent failure or a confusing generic error. lib/ai/chat/handler.ts calls this to pick a config before making a request, and separately catches a live QuotaExhaustedError from an actual 429 response mid-call to retry against the user's key if the platform key ran out unexpectedly between the check and the call.

What people usually miss

Watch out

"Encrypted at rest" only matters if the decryption path is actually restricted. Encrypting a key in the database is close to pointless if the application code (or a bug in an authorization check) will decrypt and return it to the wrong user's request — encryption protects against database access, not against a broken access-control path in the app itself.
A distinct "no key available" error is a real design choice, not a nicety. Throwing the same generic error whether the platform is out of quota, the user never connected a key, or something else entirely failed makes it impossible for the UI to tell a user what action would actually fix it.
BYO key support doesn't mean sending the key to the client. The key is used server-side to make the provider call on the user's behalf; the client never needs to see the raw key value again after it's submitted once, and shouldn't.
This is a genuinely unresolved tradeoff in real systems, not a solved problem with one right answer. A team choosing between a database-native vault feature and application-level encryption is making a real architectural call with real tradeoffs on both sides, not picking between "the correct way" and "the wrong way."

Why this matters in interviews

"How would you let users bring their own API key safely?" is a real question, and a strong answer names both the fallback-ladder mechanics (platform key, then user key, then a clear error) and the storage/security constraint (server-side, encrypted, never readable by another user or an unauthorized path) — not just "encrypt it," which is necessary but not sufficient on its own.