BYOK (Bring Your Own Key)

BYOK (Bring Your Own Key) registers a provider's metered API key with PleumRouter and routes requests through that key. Use it when you already have a metered API contract with the provider and want model usage billed directly to that account.

BYOK requires no application and no account-level review. Every authenticated user can connect the presets listed in the catalog.

Preset catalog#

GET /v1/byok/catalog returns the presets (predefined provider connection settings) that can be connected. The list includes only metered presets with availability live, contract_status approved, and official zero-cost validation. The server fixes each preset's endpoint, protocol, and auth_scheme, and a request cannot change them.

Providers without official zero-cost validation, token plans, and coding plans are not listed. Consumer subscriptions such as ChatGPT, Claude, and Gemini are not listed either. They do not include metered API usage and cannot be used as BYOK credentials, so use a key from a separately billed provider API account.

{
  "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": "groq.payg.default",
      "provider": "groq",
      "kind": "payg",
      "display_name_key": "byok.preset.groq.payg",
      "display_name_en": "Groq PAYG API",
      "availability": "live",
      "contract_status": "approved",
      "endpoint": "https://api.groq.com/openai/v1/chat/completions",
      "region": "global",
      "protocol": "openai_chat",
      "auth_scheme": "bearer",
      "supported_protocols": ["openai_chat"],
      "official_price_equivalent_ref": "model_catalog.provider:groq",
      "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
    }
  ]
}

Connecting and validating a key#

POST /v1/byok/keys accepts only preset_id and api_key. Any other field, such as a custom endpoint or a negotiated price, is rejected with a 422 error. The server first confirms that the key can be stored encrypted, then sends a GET request to the preset's official zero-cost endpoint to confirm that the key authenticates. Only verified keys become active. In the request example, PLEUM_SESSION_TOKEN holds a session token (JWT).

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

A successful registration returns a key_hint that shows only the last four characters and sets verification_status to verified. A failed registration returns an error response, and the key stays in the key list with is_active set to false and verification_status set to failed.

{
  "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 keys with GET /v1/byok/keys, reverify a stored key with POST /v1/byok/keys/{id}/verify, and remove a connection with DELETE /v1/byok/keys/{id}. Registering a preset again replaces its existing key only when the new key passes verification. If verification fails, the existing active key is not overwritten and remains active. Key registration and reverification work only while BYOK is enabled, while listing and removal work regardless of whether BYOK is enabled.

Status and usage#

GET /v1/byok/status returns whether BYOK is enabled (enabled), the overage fee per 1M tokens (overage_credits_per_1m), and the weekly free token allowance (free_period_tokens). When enabled is false, registered keys are not used for routing, and requests use managed keys instead. GET /v1/byok/usage returns this week's BYOK tokens, the remaining free tokens (free_remaining_tokens), the fee charged (fee_charged_krw, in credits), and a breakdown by provider. The weekly window starts again at 00:00 UTC every Monday.

{
  "enabled": true,
  "overage_credits_per_1m": 300.0,
  "free_period_tokens": 10000000000,
  "market": "kr"
}

{
  "period_tokens": 1240000,
  "free_period_tokens": 10000000000,
  "free_remaining_tokens": 9998760000,
  "fee_charged_krw": 0,
  "by_provider": [
    {"provider": "openai", "tokens": 1240000, "fee_krw": 0}
  ]
}

Billing and routing#

The Pleum overage fee is 0 credits for the first 10 billion (10B) BYOK tokens each week. Usage above that allowance is charged 300 credits per 1M tokens. Only BYOK tokens count toward the allowance. You pay the provider directly for model usage and remain responsible for provider-account limits.

Recommendation diagnostic and compatibility API#

POST /v1/byok/recommendations accepts five fields: tool, monthly_tokens, budget (low, medium, or high), required_models, and region. A market field in the body is rejected with a 422 error. The server derives the authoritative market from the authenticated user's persisted account, and the endpoint is available only to accounts in a supported market. The response returns the top three presets (top_three) and the full comparison table (full_table). Scores reflect tool match, required models, region, market, budget match, and volume, and monthly tokens of 10 million or more favor presets suited to high volume. A preset is excluded when its provider does not offer every required model. Affiliate campaigns, fees, and reward amounts never affect the score.

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

An external referral link is issued only for a preset with referral_enabled set to true, and only when its campaign is live and official approval, attribution setup, and reward caps are all complete.

Current scope and responsibility#

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

Troubleshooting#

• 403, BYOK is not enabled: the feature is turned off. Check the enabled value in GET /v1/byok/status.
• 400, unknown_preset: the preset_id does not match a catalog ID. Copy the value from GET /v1/byok/catalog exactly.
• 409, preset_connection_unavailable: the selected preset cannot be connected now. Choose another preset from the catalog.
• 422, invalid_credentials: the provider did not authenticate the key. Check the key's permissions and status in the provider console, then register it again.
• 429: too many key registration or reverification requests reached the PleumRouter request limit, or validation_rate_limited means the provider's validation request limit was reached. Wait a short while and try again.
• 503, validation_unavailable: the provider's validation endpoint could not be reached or returned an unexpected response. The key is not activated, so try again later.
• A key with verification_status failed or verification_required: reverify with POST /v1/byok/keys/{id}/verify. A 409 response with stored_secret_unavailable means the stored key cannot be decrypted, so remove the connection and register the key again.
• 402, byok_suspended: the personal credit balance is negative, so BYOK calls are suspended. Top up credits. Once the balance returns to 0 or above, the suspension lifts automatically at the next check. Key registration and removal remain available while suspended.

Next steps#

The fee structure is in the Billing and routing section of this page, and model selection criteria are in Choose a model or route.