Recipe · checked November 20, 2026
API or developer tool that other developers pay to call
A paid API that developers call with keys: a dashboard where they sign up, create keys and see usage, an API that checks the key and a per-key rate limit on every request, and usage reported to Stripe for metered billing. It runs on Cloudflare Workers close to callers, with Postgres for accounts and keys and Redis for rate limits.
Fits when
- Customers are developers who call your service from their own code with an API key.
- You charge by usage (requests, credits or tokens), by plan with included usage, or both.
- Callers are spread out and expect low latency and clear errors.
Not for
- An internal API that only your own app calls: build it into the app instead.
- Long-running jobs behind each request (video, big exports): accept the request, queue the work, and return a job id.
- An API that moves or holds money for callers: that needs licensing review first.
The stack
| Category | Pick | Why | Pick something else when |
|---|---|---|---|
| Hosting | The API runs close to callers worldwide with no cold starts to speak of, and Workers Free covers 100,000 requests a day while you find your first customers. Workers caps CPU time per request, which suits fast API calls. |
| |
| Database | Accounts, hashed API keys, plans and usage in Postgres, reached from Workers over HTTP with Neon's serverless driver. |
| |
| Counters and cache | Per-key rate limits are a counter on every request; Upstash Redis does atomic increments over HTTP from Workers, and its rate-limit SDK has the windows built in. |
| |
| Auth | Sign-in for the developer dashboard only; the API itself checks your own API keys, not sessions. |
| |
| Payments | Metered billing: send each customer's usage to a Stripe Meter and bill per request or credit, with plans that include a free allowance. |
| |
| Key-created notices, usage alerts at 80% and 100%, and invoices. |
| ||
| Monitoring | Errors and slow requests, tagged with the key's account (never the key itself). |
| |
| Background jobsoptional | Delivers webhooks to customers' endpoints with retries and backoff, so a slow customer server doesn't slow your API. |
|
About $20/month at 1,000 users in tool bills: Resend $20; $0 for Cloudflare Workers, Neon, Upstash Redis, Clerk, Stripe, Sentry. Usage profile: 1,000 monthly active users with light use: about 100,000 requests, 3,000 emails, 200,000 analytics events and 5 GB of stored files a month, and a database under 1 GB. AI apps add 50 questions per user a month at about 4,000 input and 500 output tokens each (200M input and 25M output tokens). Internal tools are priced for 10 staff instead.
Catches that change the plan
- Workers Free allows 100,000 requests a day and 10 ms of CPU time per request; plan to move to Workers Paid ($5/month) before launch if your requests do more work than that. Source
- Upstash Redis Free covers 500K commands a month. A rate-limit check is a few commands, so the free plan runs out around a couple hundred thousand API calls a month; after that it's pay as you go. Source
- Metered billing on Stripe adds Stripe Billing's 0.7% of billing volume on top of card fees. Source
- If you deliver webhooks through QStash, every delivery attempt counts as a message, so retries to a failing customer endpoint add to the bill; Free stops at 1,000 messages a day. Source
Setup steps
Design the API contract first
Developers judge an API by its first request, its errors and its docs, and changing a public contract later breaks their code.
- Write an OpenAPI spec for the first endpoints before coding: paths, request and response schemas, and error shapes.
- Version from day one (/v1/...) and never change a field's meaning inside a version.
- Use one error format everywhere with a stable code, a message and a link to docs; return 401 for bad keys, 429 with Retry-After for rate limits, 402 or 403 for plan limits.
- Make writes safe to retry with an Idempotency-Key header.
Done when: The spec validates, and a developer can tell from it alone how to authenticate, what each endpoint returns and what every error means.
Docs: spec.openapis.org
Issue API keys you can show once and revoke anytime
Store only a hash of each key, show the full key once, and keep a short prefix so developers can tell keys apart.
- Create api_keys (account, name, prefix, sha256 hash, created, last used, revoked) and accounts (plan, Stripe customer id).
- Generate keys with a recognizable prefix (for example sk_live_) and 32+ random bytes; show the full key once at creation.
- Let developers create, name and revoke keys in the dashboard, with separate test and live keys.
- Turn on GitHub secret scanning partner patterns for your prefix later, so leaked keys can be reported to you.
db/001_keys.sqlcreate table accounts ( id uuid primary key default gen_random_uuid(), owner_user_id text not null unique, -- Clerk user id plan text not null default 'free', stripe_customer_id text unique, created_at timestamptz not null default now() ); create table api_keys ( id bigserial primary key, account_id uuid not null references accounts(id) on delete cascade, name text not null, prefix text not null, -- first 12 characters, shown in the dashboard key_hash text not null unique, -- sha256 of the full key; the key itself is never stored mode text not null check (mode in ('test','live')), last_used_at timestamptz, revoked_at timestamptz, created_at timestamptz not null default now() );src/keys.tsconst enc = new TextEncoder(); export async function newKey(mode: "test" | "live") { const bytes = crypto.getRandomValues(new Uint8Array(32)); const key = `sk_${mode}_${btoa(String.fromCharCode(...bytes)).replace(/[^a-zA-Z0-9]/g, "").slice(0, 40)}`; return { key, prefix: key.slice(0, 12), hash: await hashKey(key) }; } export async function hashKey(key: string) { const digest = await crypto.subtle.digest("SHA-256", enc.encode(key)); return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join(""); }Done when: A new key works once copied, the database holds only its hash, and a revoked key gets 401 on the next request.
Build the API on Workers: check the key, then the rate limit
Every request does the same two cheap checks before any real work.
- Scaffold a Worker with a small router (Hono works well) and put the key check and rate limit in middleware.
- Look up the key by hash; cache valid keys for a short time so most requests skip the database.
- Rate-limit per key with a sliding window in Upstash Redis and return 429 with Retry-After and rate-limit headers.
- Keep each request fast: Workers caps CPU time per request, so move heavy work to a queue and return a job id.
npm create cloudflare@latest my-api -- --framework=hono npm i @neondatabase/serverless @upstash/ratelimit @upstash/redissrc/index.tsimport { Hono } from "hono"; import { Ratelimit } from "@upstash/ratelimit"; import { Redis } from "@upstash/redis/cloudflare"; import { hashKey } from "./keys"; import { findKey, recordUsage } from "./db"; type Env = { UPSTASH_REDIS_REST_URL: string; UPSTASH_REDIS_REST_TOKEN: string; DATABASE_URL: string }; const app = new Hono<{ Bindings: Env; Variables: { accountId: string } }>(); app.use("/v1/*", async (c, next) => { const key = c.req.header("Authorization")?.replace(/^Bearer\s+/, ""); const row = key ? await findKey(c.env, await hashKey(key)) : null; if (!row || row.revoked_at) return c.json({ error: { code: "invalid_api_key", message: "Missing or invalid API key." } }, 401); const limiter = new Ratelimit({ redis: Redis.fromEnv(c.env), limiter: Ratelimit.slidingWindow(60, "1 m") }); const { success, limit, remaining, reset } = await limiter.limit(String(row.id)); c.header("RateLimit-Limit", String(limit)); c.header("RateLimit-Remaining", String(remaining)); if (!success) { c.header("Retry-After", String(Math.ceil((reset - Date.now()) / 1000))); return c.json({ error: { code: "rate_limited", message: "Too many requests." } }, 429); } c.set("accountId", row.account_id); await next(); c.executionCtx.waitUntil(recordUsage(c.env, row.account_id, row.id)); // count after responding }); app.get("/v1/hello", (c) => c.json({ ok: true })); export default app;Done when: A request with no key gets 401, the 61st request in a minute gets 429 with Retry-After, and a normal request answers in under 100 ms from a nearby region.
Count usage and bill it through Stripe
Count every billable request cheaply, then send totals to Stripe in batches, never one call per request.
- Increment a per-account, per-day usage counter after each billable request (Redis or a usage table).
- Create a Stripe Meter and a metered price; from a scheduled job, report each account's new usage with an identifier per batch so retries don't double-bill.
- Give the free plan an allowance and enforce it on the server with a clear 402 or 403 error and an upgrade link.
- Show usage to date and the projected invoice in the dashboard.
npm i stripeDone when: A test account's requests show on its Stripe invoice preview within a day, and the free allowance blocks requests past its limit with an upgrade link.
Docs: docs.stripe.com, stripe.com
Build the developer dashboard
Sign-up to first successful request should take a couple of minutes.
- Sign in with Clerk; create the account and a test key on first sign-in.
- Show a copy-paste curl request with the developer's test key filled in, and the response it returns.
- Pages for keys, usage by day, plan and billing (Stripe customer portal), and webhooks if you send them.
Done when: A new developer can sign up, copy the sample request and get a 200 from your API in under two minutes.
Docs: clerk.com
Publish docs and an SDK
Generate reference docs from the OpenAPI spec so they never drift from the API.
- Publish reference docs generated from the spec, plus a quickstart and an errors page that every error links to.
- Generate a TypeScript (and Python, if your users want it) client from the spec, or write a thin one.
- Add an llms.txt and plain-text docs so coding agents can read them.
- Keep a changelog and announce deprecations with dates before removing anything.
Done when: Every endpoint in the spec appears in the docs with a working example, and the SDK's example runs against the test key.
Docs: llmstxt.org
Send webhooks with signatures and retries
If customers need to know when something happens, sign each webhook and retry failures without blocking your API.
- Let developers register endpoint URLs and give each one a signing secret.
- Sign the body with HMAC-SHA256 and a timestamp, and document how to verify it.
- Deliver through QStash so failed deliveries retry with backoff; every retry counts as a message.
- Show recent deliveries and their responses in the dashboard so developers can debug.
npm i @upstash/qstashDone when: A webhook to an endpoint that fails twice is delivered on the third try, and the receiving code can verify its signature.
Docs: upstash.com
Launch with monitoring and a status page
Developers notice errors and latency before you do, so watch both and tell them when something's wrong.
- Add Sentry to the Worker; tag errors with account id, never the API key or request body.
- Track error rate and p95 latency per endpoint, and alert on both.
- Publish a status page and an email or RSS feed for incidents.
- Move to Workers Paid ($5/month) before launch if 10 ms of CPU per request is too little or you'll pass 100,000 requests a day.
Done when: You can see error rate and p95 latency per endpoint for the last day, and a test incident shows on the status page.
Best practices
- Store only a hash of each API key, show it once, and let developers revoke it.
- Check the key and the rate limit before any real work on every request.
- Version the API and never change a field's meaning inside a version.
- Use one error format with stable codes, and return Retry-After on 429.
- Batch usage reports to Stripe with idempotent identifiers; never report per request.
- Generate docs and SDKs from the OpenAPI spec so they match the API.
Pitfalls
- Storing API keys in plain text, so one database leak exposes every customer.
- Reporting usage to Stripe on every request, which is slow and fails under load.
- Rate-limiting per IP instead of per key, so one customer's servers block each other.
- Doing heavy work inside the request on Workers and hitting the CPU limit.
- Breaking response shapes without a new version and breaking customers' code.
- Logging full request bodies or keys in error reports.
Costs and obligations
- Hosting: Workers Free covers 100,000 requests a day; Workers Paid is $5/month when you need more CPU per request or more requests.
- Rate limits: about 3 Redis commands per request × 100,000 requests a month = 300K commands, inside Upstash Free's 500K; past that, $0.20 per 100K.
- Card fees on what you bill: 2.9% + 30¢ per charge, plus 0.7% of billing volume for Stripe Billing.
- Publish API terms covering acceptable use, rate limits, uptime promises (if any) and what you do with data sent to the API.
- If callers send personal data through the API, you're likely their data processor: offer a data processing agreement and list your vendors.
- Keep logs of key creation, revocation and admin actions; enterprise customers will ask in security reviews.
These point to obligations to check; they aren't legal or tax advice.