Add hosted API key support to a tool so Sim provides the key when users don't bring their own. Use when adding hosted keys, BYOK support, hideWhenHosted, or hosted key pricing to a tool or block.
When a tool has hosted key support, Sim provides its own API key if the user hasn't configured one (via BYOK or env var). Usage is metered and billed to the workspace.
| Step | What | Where |
|---|---|---|
| 1 | Register BYOK provider ID | tools/types.ts, app/api/workspaces/[id]/byok-keys/route.ts |
| 2 | Research the API's pricing and rate limits | API docs / pricing page (before writing any code) |
| 3 | Add hosting config to the tool | tools/{service}/{action}.ts |
| 4 | Hide API key field when hosted | blocks/blocks/{service}.ts |
| 5 | Add to BYOK settings UI | BYOK settings component (byok.tsx) |
| 6 |
| Summarize pricing and throttling comparison |
| Output to user (after all code changes) |
Add the new provider to the BYOKProviderId union in tools/types.ts:
export type BYOKProviderId =
| 'openai'
| 'anthropic'
// ...existing providers
| 'your_service'
Then add it to VALID_PROVIDERS in app/api/workspaces/[id]/byok-keys/route.ts:
const VALID_PROVIDERS = ['openai', 'anthropic', 'google', 'mistral', 'your_service'] as const
Before writing any getCost or rateLimit code, look up the service's official documentation for both pricing and rate limits. You need to understand:
creditsUsed, costDollars, tokensUsed, or similar in the response body or headersRetry-After header, error body format, etc.Search the API's docs/pricing page (use WebSearch/WebFetch). Capture the pricing model as a comment in getCost so future maintainers know the source of truth.
Our rate limiter (lib/core/rate-limiter/hosted-key/) uses a token-bucket algorithm applied per billing actor (workspace). It supports two modes:
per_request — simple; just requestsPerMinute. Good when the API charges flat per-request or cost doesn't vary much.custom — requestsPerMinute plus additional dimensions (e.g., tokens, search_units). Each dimension has its own limitPerMinute and an extractUsage function that reads actual usage from the response. Use when the API charges on a variable metric (tokens, credits) and you want to cap that metric too.When choosing values for requestsPerMinute and any dimension limits:
N hosted keys, so the effective API-side rate per key is (total requests) / N. But per-workspace limits are enforced before key selection, so they apply regardless of key count.hosting Config to the ToolAdd a hosting object to the tool's ToolConfig. This tells the execution layer how to acquire hosted keys, calculate cost, and rate-limit.