A reverse proxy for the Discord API, deployed as a Cloudflare Worker. Adds authentication, token management, snowflake validation, and a skeleton for server-side business logic endpoints on top of the standard Discord API. Original motivation was for my Google Sheets to be able to call the Discord API, without my requests being rejected from Discord, because they would detect Google's IP addresses.
- Reverse proxy - forwards any path to
discord.com/api/v10with the token injected. (configuration) - Bot and user tokens - picked per request by header or path, with an optional premium slot. (token pool)
- Token pool - rotates registered user tokens with per-bucket cooldowns in a Durable Object. (token pool)
- Client identity - one consistent, version-tracked browser fingerprint per user token. (client identity)
- Identity guard - per-bucket budgets and captcha circuits for user tokens, plus a shared Cloudflare circuit for user and bot requests. (client identity)
- Humanized sends - optional typing indicator and length-scaled delay before a message. (configuration)
- Admin API - manage pool tokens, fingerprints, and identities behind a separate key. (token pool)
- Snowflake validation - malformed ids answer a Discord-shaped 400 before any upstream call. (configuration)
- Uniform 429s - one JSON envelope that keeps
Retry-Afterand guard signals. (configuration) - Custom endpoints - a
/custom/*skeleton with a paced, guarded message pager. (custom endpoints) - Public healthcheck - unauthenticated
GET /healthcheckwith build metadata. (configuration)
Prerequisites: Bun 1.x. Wrangler is installed as a dev dependency.
bun installCreate .dev.vars in the repo root (see .dev.vars.example for the optional keys):
DISCORD_TOKEN_BOT=your-bot-token
DISCORD_TOKEN_USER=your-user-token
AUTH_KEY=your-api-keyGenerate AUTH_KEY from at least 32 cryptographically random bytes, for example with openssl rand -base64 32. If enabling AUTH_KEY_PREMIUM or AUTH_KEY_ADMIN, generate each separately and never reuse a value across these keys. See Configuration for the consequences of key reuse.
Start the dev server and send a first request:
bun run dev
curl -H "x-auth-key: your-api-key" -H "X-Proxy-Context: user" http://127.0.0.1:8787/users/@meCaution
I advise to use an alt account for the user token to avoid any future risks for your main account of being banned by Discord.
/healthcheck and /admin/* are mounted before the main pipeline. Everything else passes through:
Rate Limit Interceptor -> Auth -> Discord Context -> Snowflake Validator -> Identity -> Subrequest Logger -> Custom Routes -> Proxy Forwarder
X-Proxy-Context: user|botpicks the token; without it,/guildspaths use the user token and everything else the bot token.AUTH_KEYselects the default user token,AUTH_KEY_PREMIUMthe premium one; allow-listed read routes rotate through the registered pool first.- Pool tokens and static user tokens are leased from the guard immediately before each Discord call and released right after.
- Bot requests check the shared Cloudflare circuit before dispatch and report Cloudflare edge blocks afterward, without user-token budgets, captcha circuits, or leases. Missing bindings or optional circuit RPCs and failed circuit RPCs degrade to unguarded bot handling.
The full diagram and source layout are in Architecture.
| Header | Direction | Purpose |
|---|---|---|
x-auth-key / Authorization |
request | AUTH_KEY or AUTH_KEY_PREMIUM; required. |
X-Proxy-Context |
request | user or bot: force the token type. |
X-Proxy-Token |
request | auto, static, or a pool label. |
X-Proxy-Typing |
request | on: typing indicator plus humanized delay before a message send. |
X-Proxy-Typing-Max-Ms |
request | 1000-30000: longer typing for long messages. |
X-Proxy-Block |
response | bucket, capacity, captcha, or cloudflare on a proxy-held 429, including pool cooldown and circuit holds. |
Details and status codes: Configuration.
- Configuration - secrets, bindings, headers, and response signals
- Token pool - token selection,
X-Proxy-Token, and the admin API - Client identity - fingerprints, the identity guard, and operating rules
- Architecture - the middleware pipeline and source layout
- Custom endpoints - building server-side endpoints under
/custom - Deployment - the CI/CD pipeline and required secrets
- Roadmap - deferred work and accepted gaps
| Command | Purpose |
|---|---|
bun run dev |
Local dev server at http://127.0.0.1:8787 |
bun run test |
Run all tests (bun run test -- --ui for the Vitest UI) |
bun run lint |
Type-check (tsc --noEmit) |
bun run cf-typegen |
Regenerate worker-configuration.d.ts from wrangler.jsonc |
The suite has 564 tests across 30 files and runs inside the Workers runtime via @cloudflare/vitest-plugin. Discord API calls are mocked at the fetch level; TokenPoolDO runs in the real Durable Object simulation, and tests either inject a mock pool client or exercise the DO directly via runInDurableObject.
See CONTRIBUTING for the branch and commit conventions.
Pushes to main run CI. Promoting to production goes through a main -> production PR that a collaborator approves with /approve, which fast-forwards production; a push to production deploys the Worker with Wrangler. The workflows and required secrets are described in Deployment.