BYOK

Two keys

Key	Role
Kasva API key	Auth to our gateway (Authorization: Bearer …)
Provider keys (Groq / DeepSeek / Gemini / OpenAI / Anthropic / xAI / fal.ai)	Paid by you; used for upstream inference

Without provider BYOK, chat runs on Kasva hosted open models when the operator DigitalOcean key is set. Operator Groq/Gemini/DeepSeek env secrets are not used on public routes. Cloudflare Workers AI is not a public route.

Recommended: KV register (Cursor)

Register once, then Cursor only needs the Kasva key.

1. Save keys

curl -X POST https://kasva.dev/v1/byok/keys \
  -H "Authorization: Bearer YOUR_KASVA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"groq":"gsk_...","deepseek":"sk_...","gemini":"AIza...","openai":"sk-...","xai":"xai-...","fal":"..."}'

Partial update is fine — omit a field to leave it unchanged. Send "" to delete that provider.

2. Check status (no secrets returned)

curl https://kasva.dev/v1/byok/keys \
  -H "Authorization: Bearer YOUR_KASVA_KEY"

{
  "object": "byok.keys",
  "configured": { "groq": true, "deepseek": false, "gemini": true, "openai": false, "anthropic": false, "xai": false, "fal": false }
}

3. Cursor

1. Settings → Models → OpenAI API Key = YOUR_KASVA_KEY
2. Override OpenAI Base URL = https://kasva.dev/v1
3. Add custom model: kasva/auto or kasva/code (not Cursor’s built-in Auto)
4. Use Chat / Ask; Agent needs tool-capable models

4. Chat

curl https://kasva.dev/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KASVA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kasva/auto","messages":[{"role":"user","content":"Hello"}]}'

Keys: KV only

Register provider keys with POST /v1/byok/keys. Per-request X-Kasva-*-Key headers are not accepted.

GET /v1/models shows byok/<provider>/… only when that provider key is configured on your account.

Priority

1. KV for that Kasva key (POST /v1/byok/keys)
2. Kasva hosted / free-route fallback (no BYOK)

Free-route (limit / auth fail)

When an upstream returns 401 / 402 / 403 / 429 / 503, Kasva walks the user’s remaining BYOK providers, then Kasva hosted:

Order: Groq → Gemini → DeepSeek → Kasva hosted

Already-tried providers are skipped. Response kasva.route_reason shows hops, e.g. groq 429, free-route → byok/gemini/2.5-flash.

Proactive KV rate counters (B-026) are still separate; this is reactive failover.

Cline / VS Code Copilot custom endpoint

Same Base URL + Kasva key. Prefer KV registration so you do not put provider keys in client config.

• Turn off Auto-approve Read if the agent starts scanning node_modules
• Prefer Act mode only with models that return native tool_calls

Security

• Never commit provider keys or put them in frontend JS
• GET /v1/byok/keys never returns secret values
• KV stores byok:{sha256(api_key)} → JSON keys
• Rotate: POST with a new key, or "" to clear