A small FastAPI app for Railway where every request needs an API key. The key check, rate limits, quotas and usage counting are done by the UsageRail Python SDK (https://usagerail.com) inside the app, so requests don't pass through a gateway. UsageRail turns the counts into usage billing in your own Stripe account.
One Railway service running uvicorn with this app:
| Route | What it does | Usage counted |
|---|---|---|
GET /v1/hello |
Returns {"message": "Hello"} |
1 request |
POST /v1/word-count |
Takes {"text": "..."} and returns the number of words |
1 request, or one unit per word if your UsageRail app counts units |
Every path, including /, goes through the UsageRail middleware first. A request without a valid key gets a 401 before your code runs. A customer over their rate limit, or over a quota set to stop at the limit, gets a 429 with a Retry-After header.
Files:
main.py: the app and the middleware setuprequirements.txt:usagerail,fastapi,starletteanduvicorn, pinnedrailway.json: start commanduvicorn main:app --host 0.0.0.0 --port $PORT.python-version: Python 3.12
The app won't start without it. To get one:
- Sign in to the UsageRail console at https://app.usagerail.com and choose New app.
- Pick Test mode, the SDK integration, and a key prefix such as
acme. - Copy the app key (it starts with
urk_test_). The console shows it only once.
Paste it into the service's Variables tab on Railway. The quickstart at https://usagerail.com/docs/quickstart covers these steps and what each field means.
Give the service a public domain (Settings, Networking, Generate Domain). Then, in the UsageRail console, open Customers, add a customer and create a key for them. Use that key below; acme_test_... stands for it.
curl -i https://your-app.up.railway.app/v1/hello \
-H "Authorization: Bearer acme_test_..."The response is 200 with {"message":"Hello"}. Without the header:
curl -i https://your-app.up.railway.app/v1/helloHTTP/1.1 401 Unauthorized
{"error": "invalid_api_key"}The key can also go in an X-API-Key header:
curl -i -X POST https://your-app.up.railway.app/v1/word-count \
-H "X-API-Key: acme_test_..." \
-H "Content-Type: application/json" \
-d '{"text": "metered APIs bill per unit"}'That returns {"words":5}. If the app's Settings say it counts units, this request counts as 5.
To see a rate limit, create a plan under Plans with a limit of 2 requests per second and move the customer to it. The SDK syncs every 15 seconds, so wait for the next sync, then send a burst:
for i in 1 2 3 4 5; do
curl -s -o /dev/null -w "%{http_code}\n" https://your-app.up.railway.app/v1/hello \
-H "Authorization: Bearer acme_test_..."
doneRequests over the 2-per-second limit get 429. How many depends on how fast they go out, since the limit refills during the burst.
Counts reach the console's Usage page about a minute after the requests.
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
USAGERAIL_APP_KEY=urk_test_... uvicorn main:app --port 8000- The SDK sends counts every 60 seconds and once more when uvicorn shuts down on SIGTERM. If the process is killed outright, for example when it runs out of memory, counts it hadn't sent are lost and never billed.
- If the SDK can't reach UsageRail, it checks synced keys against its local copy for up to 24 hours after the last successful sync. A key it has never seen gets a
503by default; you can change that in the app's settings. - Middleware options, counting units with
request.state.usagerail.track(), and using your own login instead of UsageRail keys are covered at https://usagerail.com/docs/fastapi.
MIT