Skip to content

How to Onboard a Consuming App with BYOK

Last verified: 2026-07-26 against dev at f0388abb.

Use this guide when another application calls SDP and needs its own LiteLLM virtual key used for LLM-backed SDP work.

Current Status

The detailed BYOK design is still marked draft in docs/design/byok-llm-keys-tdd.md. Treat this guide as the operational shape to follow once that design is accepted.

Required Pattern

  • The consuming app stores its LiteLLM virtual key in its own vault.
  • The browser never sees the key.
  • The consuming app's server-side backend/BFF forwards the key to SDP over internal HTTPS.
  • SDP authenticates the caller separately from the LLM key.
  • SDP uses the key transiently for the request and never stores or logs it.

Procedure

  1. Create or identify the consumer's LiteLLM virtual key.
  2. Store it in the consumer's Key Vault and hydrate it into the consumer server environment with envsync.
  3. Route browser-originated requests through the consumer server tier.
  4. Add X-AltaForge-LLM-Key only on the server-to-SDP request.
  5. Confirm SDP redacts that header from logs, traces, and errors.
  6. Verify missing/bad key behavior and caller-auth failure behavior separately.

Verification

  • Browser network tools never show the LLM key.
  • A valid caller with a valid key can run the LLM-backed SDP path.
  • A request without caller auth fails authorization even if it has an LLM key.
  • A rejected LLM key maps to a clean upstream-key error and does not leak the key.