Quickstart: your first metered request

This walks through one small Express API: create an app, add the middleware, give a customer a key, and watch the request show up in the console. It takes about ten minutes. For other frameworks the steps are the same and only the code changes; see the pages under Frameworks.

1. Create an app

In the console, choose New app and fill in:

• Mode: Test. Test and live are separate apps, each with its own customers and keys.
• Integration: SDK. Pick HTTP check only if your API is written in a language without an SDK. You can't switch an app to the other integration later.
• API key prefix: the start of every key your customers get, such as acme in acme_test_.... Use 2 to 10 lowercase letters or digits.

After you choose Continue to setup, the console shows the app key once. Put it in your server's environment:

USAGERAIL_APP_KEY=urk_test_...

While you're in the console, check the app's time zone under Settings. Monthly quotas reset at midnight in that zone, and you can't change it once the app has recorded usage.

2. Install the SDK

In a new folder:

npm init -y
npm pkg set type=module
npm install @usagerail/node express

The second line lets server.js use import. In an existing Express project, npm install @usagerail/node is enough.

3. Add the middleware

Put the middleware before your routes:

import express from "express";
import { usageRail } from "@usagerail/node/express";

const app = express();

app.use(usageRail({
  appKey: process.env.USAGERAIL_APP_KEY,
  auth: "api-key",
}));

app.get("/v1/hello", (req, res) => {
  res.json({ message: "Hello" });
});

app.listen(3000);

Start it with the environment file:

node --env-file=.env server.js

Within a few seconds the server syncs with UsageRail for the first time, and the app's page in the console shows "SDK connected".

4. Give a customer a key

In the console, open Customers, choose Add customer, then Create key on the customer's page. The key is shown once, so copy it.

Call your API with it:

curl -i http://localhost:3000/v1/hello \
  -H "Authorization: Bearer acme_test_..."

You get your handler's 200 response. A key created a moment ago works right away: if the SDK hasn't synced it yet, it asks UsageRail about that key directly.

Now leave the key out:

curl -i http://localhost:3000/v1/hello

The middleware answers before your handler runs:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"invalid_api_key"}

5. See the request in the console

The SDK sends its counts every 60 seconds. About a minute after your first call, the Usage page shows it under the customer and the GET /v1/hello route. The 401 is there too, as a rejected request. Rejected requests are recorded for analytics and never count as usage.

6. Add a rate limit

Under Plans, create a free plan with a limit of 2 requests per second, then open the customer and move them to that plan. The SDK picks up the change at its next sync, within 15 seconds.

Send five requests in a row:

for i in 1 2 3 4 5; do
  curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/v1/hello \
    -H "Authorization: Bearer acme_test_..."
done

The first two get 200 and the rest get 429, with a Retry-After header that says how many seconds to wait. Rate limits are checked in your process, so refusing these requests takes no network call.

Next steps

• Express middleware: counting tokens or other units, using your own authentication, and changing the rejection responses.
• API keys: rotation, revocation and what happens while UsageRail is unreachable.
• Quotas: monthly limits and how the SDK enforces them without a network call per request.