Getting Started

Sign up, add a provider key you already hold, create a FreeRouter key routed at it, and send your first request. Budget about five minutes.

Prerequisites

  • An email address (or a Google account) to sign up.
  • An API key for at least one supported gateway, such as OpenRouter — see Providers. New accounts do not come with inference credit.
  • Your gateway account needs credit, or use a free model: openrouter/free answers on any OpenRouter key, funded or not. A paid model on an unfunded account comes back as a 402 (why).
  • A terminal with curl, or any SDK that takes a base URL — see Use your SDK. The dashboard playground works from the browser with no code at all.

Step 1 — Create your account

1
Sign up with Google or email + OTP
Go to app.freerouter.com/app/signup and continue with Google, or enter your email for a one-time passcode — no password to manage either way. Both land in your personal workspace, and you can use either method on the same account afterwards.

Step 2 — Add your provider key

2
Open Providers → Add provider
In the dashboard, go to Providers, choose a gateway (e.g. OpenRouter), and paste the API key you already hold for it. FreeRouter encrypts it at rest and uses it only to forward your traffic. Add as many providers as you like — you'll route across them next. (Cloudflare also asks for your account ID and gateway name; the form's How to find this links show where each value lives.)
Where keys sit: your app holds only the FreeRouter key; the dashboard holds your provider keys, encrypted; FreeRouter calls the gateway with the provider key, so the gateway never sees your FreeRouter key. Your app holds only fr_live_… Authorization: Bearer fr_live_… FreeRouter Dashboard Providers tab provider keys, encrypted at rest Proxy api.freerouter.com routing rule picks a target, swaps in its provider key Authorization: Bearer sk-or-… Gateway sees your provider key, never your FreeRouter key
Your application ships only the FreeRouter key (fr_live_…). The provider keys you paste under Providers are encrypted at rest and never returned after you save them; on each request the proxy decrypts the one its routing rule picked and sends it to that gateway. Delete a provider key and every rule that referenced it stops using it at once.
Add two providers now Routing is more useful with more than one gateway. Adding a second provider up front lets you try %-split and failover on the Routing Rules page without coming back.

Step 3 — Create a FreeRouter key

3
Keys → Create key
Go to API Keys and create a key. Pick its API shape (default openai). Under Route this key to, your providers are listed in priority order and already checked — all of them if you have up to three, otherwise the first one, and you tick the others it should fail over to (a filter helps on a long list). The key is saved with that rule, so it works on the first request. Copy the key — it looks like fr_live_... and is shown only once, next to a ready-to-paste request for its shape. A key with no routing targets answers 402 (no_route).

You can create multiple FreeRouter keys — for example a openai-shaped key for production and an anthropic-shaped key for a service that speaks the Messages API. Each key carries its own shape and routing rule.

Keys are manageable from their cards: rotate a secret (the old one stops immediately, or keeps working for 15 minutes, 1 hour or 24 hours so your apps can switch without downtime), revoke a compromised key, or delete one that never served traffic. Providers can be disabled to pause routing without losing their place in your rules, and re-enabled anytime.

Step 4 — First success, no code

4
Test key, or Playground
Each key card has a Test key button that sends a tiny live completion through the key's own routing and shows which gateway answered. Or open Playground, pick the key, pick a model from its live catalog — on an OpenRouter key, openrouter/free costs nothing — and hit Send: you get the response JSON, the routing trace, and a curl command that reproduces the call. Neither is written to request logs. Details: Usage & Spend → Playground.

Step 5 — Make your first request from code

Point any OpenAI-compatible client at FreeRouter's base URL and pass the fr_live_... key you just created. Here it is with curl, on the free model so it works before the gateway account is funded:

# Set your FreeRouter key
export FREEROUTER_API_KEY="fr_live_your_key_here"

curl https://api.freerouter.com/v1/chat/completions \
  -H "Authorization: Bearer $FREEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/free",
    "messages": [
      { "role": "user", "content": "Hello from FreeRouter!" }
    ]
  }'

Once the gateway account has credit, swap in any provider/model id it lists, such as openai/gpt-4o-mini — GET /v1/models shows what your key can reach. The same two values (base URL, key) drop into the OpenAI, Anthropic, Vercel AI, LangChain and LiteLLM SDKs: Use your SDK.

A successful response is a standard OpenAI chat completion object:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "openrouter/free",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 9, "total_tokens": 21 }
}
Which gateway answered? FreeRouter adds an X-FreeRouter-Provider response header naming the gateway that served the request, so you can confirm your routing rule is doing what you expect. Got a 401, 402 or 404 instead? Troubleshooting lists every code with its fix.

Next steps

Next Quickstart — pick your path