Bring your own keys (BYOK)

With BYOK you supply your own engine API keys. GroundRoute routes on your keys, so you pay the engine directly and GroundRoute charges nothing on a cache miss. You still get routing, failover, caching, and governance across all six engines through one API.

Supported providers

You can add a key for any of the six engines:

serper, brave, exa, tavily, firecrawl, perplexity.

How keys are stored

Validated on save. When you add a key, GroundRoute makes a live call to that provider to confirm the key works before storing it. An invalid or provider-rejected key returns 400; if the provider is temporarily unreachable for validation, you get 503 (transient — retry).
Encrypted at rest. Keys are encrypted before storage.
Never re-displayed. The plaintext key is never returned again. Listing shows only the provider, status, and a short non-reversible fingerprint prefix — never the key or its ciphertext.

Managing engine keys (console)

Manage BYOK keys from the console, or via the console API (tenant-scoped through your console session).

Add a key

POST /console/provider-keys

// request
{ "provider": "serper", "key": "your-serper-api-key" }

// response (201) — note: the key itself is never echoed back
{
  "id": "…",
  "provider": "serper",
  "fingerprint_prefix": "a1b2c3d4e5f6",
  "status": "active",
  "created_at": "2026-06-14T07:48:14Z"
}

List (masked)

GET /console/provider-keys returns one entry per stored key — id, provider, fingerprint_prefix, status, created_at. No plaintext, ever.

Delete

DELETE /console/provider-keys/{key_id} revokes a stored key (404 if it isn't yours).

BYOK vs managed billing

Your BYOK status is resolved server-side at auth time from whether you have an active provider key — it is never read from a request body.

	Cache miss	Cache hit
BYOK (your key)	$0 to GroundRoute — you paid your own engine	50% of `cost_avoided_usd`
Managed (GroundRoute's key)	pass-through provider cost, no markup	50% of `cost_avoided_usd`

So with BYOK you only ever pay GroundRoute for the value the cache creates. A free account is BYOK-only (capped and rate-limited) and is never charged. Managed searches require a paid tier with billing on file. See Pricing.

Per-call, the response tells you which key served it: usage_meta.provider_key_source is byok or platform (managed).

PreviousCaching NextPricing