BYOK provider keys in the model gateway

The app.nz gateway supports bring-your-own-key because many teams already have provider contracts, credits, or compliance requirements. BYOK lets them route through app.nz without forcing all traffic onto app.nz-owned provider accounts.

The hard part is doing that without turning the gateway into an open relay or a secret-management accident.

One active key per provider

Users store provider keys under their account. The gateway keeps one active key per provider and revokes the old one when a replacement is saved. That keeps selection simple:

request resolves to provider look for user's active key for provider use it if present otherwise use platform key if configured otherwise skip that provider

This priority order is important. A user's BYOK key should win over the platform key because it is an explicit routing and billing choice.

Provider validation

The save endpoint validates that the provider exists in the model catalogue or in the embedded seed catalogue. That catches typos early and avoids storing random strings as provider names.

The embedded seed catalogue matters in fresh clones and CI. The platform should still understand common providers before the generated catalogue has been synced.

Secret storage

Provider keys are stored in the database with a prefix and last four characters for UI display. The full key can be encrypted at rest with the gateway secret key. If the encryption key is not configured, the server logs that BYOK storage is running without at-rest encryption.

The UI should never need the full key again. It needs:

• provider,
• prefix,
• last four,
• created time,
• revoked status.

A key management screen should confirm what exists without handing secrets back to the browser.

Routing behavior

BYOK is not a separate gateway. It uses the same catalogue, fallback logic, provider adapters, logging, and metering code as platform-key traffic.

That avoids a common bug: the BYOK path working for simple OpenAI chat while failing for Anthropic, Google-compatible paths, images, or fallback chains. Key selection should be a small step inside the normal route, not a parallel implementation.

Abuse boundary

The gateway requires auth when no free platform key path is intended. An unauthenticated default would be an open relay, which is both expensive and abusable.

BYOK helps here because a caller can use app.nz routing while still being accountable to their own upstream provider. But app.nz still needs to enforce its own auth, rate limits, and model access rules.

Why teams want it

BYOK is not just about cost. It lets teams:

• keep usage under existing enterprise agreements,
• test app.nz routing without moving procurement,
• isolate provider spend by account,
• use providers app.nz supports but does not fund globally,
• retain analytics in app.nz while billing upstream directly.

The product goal is to make the key boring. Users should save it once, see that it is active, and then keep using the same model names and APIs.