Two Keys in One Request Path: When the Aggregator Routes to Your BYOK Key and When It Falls Back

Why Two Keys in One Request Path?

When you send a request to an aggregator, two possible credentials can serve it: your own bring-your-own-key (BYOK) key or a key managed by the aggregator's shared pool. Understanding which key is used—and when—helps you control costs, troubleshoot errors, and verify billing.

This article explains the routing decision for a single API call, covering model selection, failover, and verification.

How Routing Decisions Are Made

The aggregator evaluates each request against your account settings and the requested model. The goal is to honor your preferences while ensuring reliability.

Key factors include:

• BYOK preference: Whether you have registered a personal API key for the requested model provider.
• Model availability: Whether the provider's endpoint is reachable and the model is available.
• Failover policy: Whether the aggregator should fall back to a shared pool key if your BYOK key fails.
• Rate limits and quotas: Whether your BYOK key has remaining capacity.

BYOK vs. Shared Pool: The Trade-offs

| Aspect | BYOK Key | Shared Pool Key |
|--------|----------|-----------------|
| Billing | You pay the provider directly | You pay the aggregator (official price × 1.3) |
| Control | Full control over usage limits | Managed by aggregator |
| Reliability | Depends on your key's validity | Aggregator handles multiple keys |
| Cost | Provider's official rates | Aggregator's markup |

If you are a key contributor (you provide keys that others use), you earn credits: official price × 1.1 (standard) or × 1.2 (premium) in USDC.

Failover: When BYOK Fails

If your BYOK key returns an error (e.g., invalid key, rate limit, or outage), the aggregator can automatically fall back to a shared pool key. This ensures your request still succeeds, but billing shifts to the aggregator's shared pool rate.

Failover is typically configurable:

• Strict BYOK: Request fails if your key is unavailable.
• Allow fallback: Aggregator uses shared pool if BYOK fails.

The default is usually to allow fallback for reliability.

Verifying Which Key Served the Response

To confirm which key was used, check the response headers or metadata. Common indicators:

• Response headers: Look for a custom header like X-Provider-Key-Source or similar.
• Response body: Some aggregators include a key_source field in the JSON response.
• Logs: Your aggregator dashboard may show per-request key usage.

If no explicit indicator exists, you can infer by comparing the response time, error patterns, or billing records.

Example: A Single Request Flow

1. You send a request for model claude-3-opus with your API key.
2. The aggregator checks if you have a BYOK key for Anthropic.
3. If yes, it attempts to use your key.
4. If your key fails (e.g., insufficient credits), and fallback is allowed, it routes to a shared pool key.
5. The response includes metadata indicating which key was used.
6. Billing reflects the actual key used.

Best Practices

• Set fallback preferences based on your tolerance for cost vs. reliability.
• Monitor key usage via aggregator logs to avoid unexpected charges.
• Rotate BYOK keys regularly for security.
• Use strict BYOK when you need to enforce provider-level controls.

Conclusion

Routing between BYOK and shared pool keys is a core feature of API aggregators. By understanding the decision logic and verification methods, you can optimize for cost, control, and reliability. Always check your aggregator's documentation for specific header names and configuration options.