feat: add API key selection by ID with priority over name selection

[Pratham-Mishra04]

Summary

Adds support for explicit API key selection by ID through a new BifrostContextKeyAPIKeyID context key and x-bf-api-key-id header. When both key ID and key name are provided, the ID takes priority over name-based selection.

Changes

• Added BifrostContextKeyAPIKeyID constant for key selection by ID
• Modified key selection logic in selectKeyFromProviderForModel to prioritize ID over name
• Added x-bf-api-key-id header support in HTTP transport layer
• Updated documentation to reflect the new key selection options and priority behavior

Type of change

• Feature
• Bug fix
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (Next.js)
• Docs

How to test

Test key selection by ID:

# Test with key ID header
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-api-key-id: your-key-uuid' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

# Test priority: ID should override name when both are present
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-api-key-id: key-uuid-1' \
--header 'x-bf-api-key: key-name-2' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Test with Go SDK:

ctx := context.WithValue(ctx, schemas.BifrostContextKeyAPIKeyID, "your-key-uuid")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), request)

Run standard tests:

# Core/Transports
go version
go test ./...

# UI
cd ui
pnpm i || npm i
pnpm test || npm test
pnpm build || npm run build

Screenshots/Recordings

N/A - Backend API enhancement

Breaking changes

• Yes
• No

This is an additive feature that maintains backward compatibility with existing key name selection.

Related issues

N/A

Security considerations

The new key ID selection follows the same security model as existing key name selection. Key IDs are resolved server-side against configured provider keys, maintaining the same access control and validation patterns.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[Pratham-Mishra04]

• feat/prompt-playground-ui-components #1885
• prompt repository changes #1466
• feat: add API key selection by ID with priority over name selection #1941 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 25933375-ac97-43b0-9247-3be0faed5274

📥 Commits

Reviewing files that changed from the base of the PR and between ff457b1 and 12b2519.

📒 Files selected for processing (10)

• AGENTS.md
• core/bifrost.go
• core/changelog.md
• core/schemas/bifrost.go
• core/schemas/context.go
• docs/features/keys-management.mdx
• docs/providers/request-options.mdx
• docs/quickstart/go-sdk/context-keys.mdx
• transports/bifrost-http/lib/ctx.go
• transports/changelog.md

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added API key selection by ID (x-bf-api-key-id) with priority over name-based selection when both are provided
  • Applicable across Go SDK, Gateway, and HTTP transport layers

• Documentation

  • Updated API key selection guides to explain ID-based selection, precedence rules, and usage examples across multiple documentation pages

Walkthrough

This change introduces a new API key selection mechanism using BifrostContextKeyAPIKeyID (header x-bf-api-key-id) that takes precedence over the existing name-based selection. The feature is implemented across the core logic, schemas, transport layer, and documentation.

Changes

Cohort / File(s)	Summary
Core Logic & Schemas core/bifrost.go, core/schemas/bifrost.go, core/schemas/context.go	Implements APIKeyID selection with priority over APIKeyName. Adds the APIKeyID constant, includes it in reserved keys, and updates key selection logic to check ID first with fallback to name-based selection.
Transport Layer transports/bifrost-http/lib/ctx.go	Adds parsing and mapping of the x-bf-api-key-id header into the Bifrost context under the APIKeyID field.
Documentation docs/features/keys-management.mdx, docs/providers/request-options.mdx, docs/quickstart/go-sdk/context-keys.mdx	Updates API key selection documentation to include ID-based selection alongside name-based selection, with examples showing the priority precedence where ID takes priority over name.
Changelog Entries AGENTS.md, core/changelog.md, transports/changelog.md	Documents the new APIKeyID feature across markdown documentation and changelog files.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Transport as HTTP Transport<br/>(bifrost-http)
    participant Core as Core Logic<br/>(bifrost)
    participant KeyStore as Key Store
    
    Client->>Transport: Request with x-bf-api-key-id<br/>or x-bf-api-key header
    Transport->>Transport: Parse headers into context
    Transport->>Core: ResolveAPIKey(ctx)
    Core->>Core: Check if APIKeyID present?
    alt APIKeyID Present
        Core->>KeyStore: Find key by ID
        KeyStore-->>Core: Return key or error
    else APIKeyID Not Present
        Core->>Core: Check if APIKeyName present?
        alt APIKeyName Present
            Core->>KeyStore: Find key by name
            KeyStore-->>Core: Return key or error
        else Neither Present
            Core-->>Core: Return error
        end
    end
    Core-->>Client: Return API key or error

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A curious rabbit hops through the code,
New keys by ID now light up the road,
Priority flows where names used to reign,
Selection grows wise, more precise, more sane!
Headers transformed, documentation's bright—
The gateway now chooses with exquisite sight. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately describes the main feature: adding API key selection by ID with priority over name selection, directly matching the primary changeset.
Description check	✅ Passed	The PR description is comprehensive and follows the template, including all major sections: Summary, Changes, Type of change, Affected areas, How to test, Breaking changes, Security considerations, and Checklist.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 03-05-feat_added_support_to_id_based_key_selection

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}