Bring your own AI key.

Overview.

Wendesk routes every AI call through src/modules/ai/quota-router.ts. The router decides — per call — whether to use the platform LLM (free quota) or your configured provider key (BYOK). Direct provider SDK calls outside the router are blocked at build time.

All AI usage is logged to the AiUsageQuota table — tokens-in, tokens-out, model, latency, cost, tenantId — for billing and observability.

Free quota.

Each plan includes a monthly token allowance on the platform model:

• Base: 50,000 tokens/mo
• Starter: 250,000 tokens/mo
• Growth: 1,000,000 tokens/mo
• Pro: 5,000,000 tokens/mo
• Enterprise: custom contracted (with cost+20% overage)

BYOK fallback chain.

When your free quota is exhausted, the router applies this priority:

1. Check tenant quota

   If the tenant has free tokens left → use platform Bedrock.

2. Check BYOK key

   Quota exhausted + tenant has a configured BYOK key → use the tenant's key.

3. Enterprise overage

   No BYOK + Enterprise plan → overage at provider cost +20% (post-paid invoice).

4. Block with upgrade CTA

   No BYOK + Starter/Growth/Pro → block with friendly upgrade CTA.

Configure a provider.

Pick the provider you want to bring keys for. All four follow the same flow: get a key from the provider's console → paste into Wendesk Admin → optionally pick a model. Keys are envelope-encrypted with AWS KMS Customer Managed Keys.

# Quick test — list available models
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-proj-XXXX..." \
  | jq '.data[] | .id' | head

# Or — fire a one-token test
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-proj-XXXX..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":1}'

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: sk-ant-api03-XXXX..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5-20251001",
    "max_tokens": 50,
    "messages": [{"role":"user","content":"Reply with just OK"}]
  }'

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=AIzaSyXXXX..." \
  -H "Content-Type: application/json" \
  -d '{ "contents": [{ "parts": [{ "text": "Reply with just OK" }] }] }'

# Configure AWS CLI
aws configure
# Enter Access Key, Secret, region (ap-south-1)

# Test Bedrock model access
aws bedrock list-foundation-models \
  --region ap-south-1 \
  --query "modelSummaries[?contains(modelId,'claude')].modelId"

Security & logging.

Every BYOK key is encrypted at rest with AES-256-GCM envelope encryption using an AWS KMS-managed Customer Managed Key (CMK). On Pro+ plans, keys live in the tenant's dedicated database (separate logical DB per tenant). Never logged. Never returned by any API endpoint. Decrypted only at request time inside our trust boundary.

All AI calls are logged to AiUsageQuota: tokens-in, tokens-out, model, latency, cost, tenantId. Used for quota enforcement and billing. Healthcare tenants (industry = healthcare): PHI is auto-redacted at the call site BEFORE sending to the provider. Redaction events are logged.

Troubleshooting.

• "Invalid API key" → key was revoked, expired, or you copy-pasted a typo. Re-copy from provider console.
• "Insufficient quota" on OpenAI → you have a key but no billing set up; add a card at platform.openai.com/account/billing.
• "Model not found" → model ID changed (provider-side); update the default model under Wendesk Settings.
• "Rate limit exceeded" → you hit your provider's per-minute/hour limit; upgrade your tier or use a different provider for the burst.
• Bedrock "AccessDeniedException" → IAM policy missing bedrock:InvokeModel, or you didn't request model access in the AWS console.