BYOK (Bring Your Own Key)

BYOK (Bring Your Own Key) stores an API key issued by a provider's metered API account in encrypted form and routes requests through it. You pay the provider directly for model usage and pay PleumRouter only a service fee in credits after the free allowance.

Status and usage#

GET /v1/byok/status returns operational status, the above-allowance service fee, and the monthly free token allowance. GET /v1/byok/usage returns this month's UTC-based BYOK tokens, remaining allowance, credits charged, and provider breakdown. The monthly window resets at 00:00 UTC on the first day of each month.

{
  "enabled": true,
  "fee_percent": 1.0,
  "free_monthly_tokens": 1000000000,
  "market": "kr"
}

{
  "month_tokens": 1240000,
  "free_monthly_tokens": 1000000000,
  "free_remaining_tokens": 998760000,
  "fee_charged_krw": 0,
  "by_provider": [
    {"provider": "openai", "tokens": 1240000, "fee_krw": 0}
  ]
}

Preset catalog#

GET /v1/byok/catalog returns immutable server-owned presets. Connections are limited to PAYG presets with availability=live, contract_status=approved, connection_enabled=true, and official zero-cost validation. Each endpoint, protocol, and auth scheme is fixed by the preset and cannot be supplied by the user.

Information-only token plans, coding plans, and consumer subscriptions offer information and an interest action only. Consumer subscriptions such as ChatGPT, Claude, and Gemini do not include metered API usage and cannot be used as BYOK credentials; a separately billed provider API account is required.

{
  "data": [
    {
      "preset_id": "openai.payg.default",
      "provider": "openai",
      "kind": "payg",
      "display_name_key": "byok.preset.openai.payg",
      "display_name_en": "OpenAI PAYG API",
      "availability": "live",
      "contract_status": "approved",
      "endpoint": "https://api.openai.com/v1/chat/completions",
      "region": "global",
      "protocol": "openai_chat",
      "auth_scheme": "bearer",
      "supported_protocols": ["openai_chat"],
      "official_price_equivalent_ref": "model_catalog.provider:openai",
      "validation": {"kind": "openai_models", "zero_cost": true},
      "allowed_use_key": "byok.provider_api_key_only",
      "allowed_use_en": "Use an API key issued for this provider's metered API account.",
      "connection_enabled": true,
      "referral_enabled": false
    },
    {
      "preset_id": "openai.chatgpt-subscription",
      "provider": "openai",
      "kind": "consumer_subscription",
      "display_name_key": "byok.preset.openai.chatgpt-subscription",
      "display_name_en": "ChatGPT Consumer Subscription",
      "availability": "info_only",
      "contract_status": "not_api_compatible",
      "endpoint": null,
      "region": "global",
      "protocol": "openai_chat",
      "auth_scheme": "bearer",
      "supported_protocols": ["openai_chat"],
      "official_price_equivalent_ref": null,
      "validation": {"kind": "none", "zero_cost": false},
      "allowed_use_key": "byok.separate_api_billing_required",
      "allowed_use_en": "ChatGPT subscriptions do not include metered API usage; use a separately billed API key.",
      "connection_enabled": false,
      "referral_enabled": false
    }
  ]
}

Connecting and validating a key#

POST /v1/byok/keys accepts exactly preset_id and api_key. It accepts neither a user endpoint nor negotiated prices. The server first proves that encrypted storage is available, then validates through the preset's official zero-cost endpoint. Only verified credentials become active.

curl -X POST https://apirouter.pleum.ai/v1/byok/keys \
  -H "Authorization: Bearer <session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "preset_id": "openai.payg.default",
    "api_key": "sk-..."
  }'

The response contains a key_hint exposing only the last four characters and the server's verification state, never plaintext. A failed registration may remain visible as inactive/failed; its bounded error code contains no secret value.

{
  "id": "b1f2c3d4-...",
  "preset_id": "openai.payg.default",
  "provider": "openai",
  "kind": "payg",
  "key_hint": "••••a1b2",
  "is_active": true,
  "verification_status": "verified",
  "verification_attempted_at": "2026-08-12T09:00:00Z",
  "verified_at": "2026-08-12T09:00:00Z",
  "last_verification_error": null,
  "created_at": "2026-08-12T09:00:00Z"
}

List credentials with GET /v1/byok/keys, reverify a stored credential with POST /v1/byok/keys/{id}/verify, and revoke it with DELETE /v1/byok/keys/{id}. Listing and revocation remain available while operations are paused, but reverification does not. Legacy credentials are verification_required and cannot route until reverified.

Billing and routing#

The Pleum service fee is 0% for the first 1 billion BYOK tokens each month. Usage above that allowance is charged 1% of the provider's official list-price equivalent in the user's market-currency credits. The live status and usage responses are authoritative. You remain responsible for provider model costs and provider-account limits.

Plan diagnostic, interest, and referrals#

POST /v1/byok/recommendations accepts only tool, estimated monthly tokens, budget band, required models, and hosting region in its body. The server derives the authoritative market from the authenticated user's persisted account and does not accept a client market. Affiliate campaigns, fees, and reward amounts never affect the score.

curl -X POST https://apirouter.pleum.ai/v1/byok/recommendations \
  -H "Authorization: Bearer <session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "coding",
    "monthly_tokens": 50000000,
    "budget": "low",
    "required_models": [],
    "region": "global"
  }'

POST /v1/byok/plans/{preset_id}/interest is idempotent for the same user and preset. Recording interest in an information-only entry does not activate connection, signup, or rewards.

An external referral link appears only when an operator-approved campaign is live and the campaign API confirms it. Affiliate and sponsored relationships are disclosed separately from ranking; without a confirmed campaign there is no external-navigation CTA. Referral-bonus settlement, grant, and reversal paths are not currently available.

Current scope and responsibility#

Manage key permissions, balance, payment method, rotation, and deletion in the provider console. PleumRouter never shows the plaintext key again.