Introduction

Meter your API — without building any of it

ReqKey is API key auth, usage credits, and request analytics as a service. It never sits in front of your API. One call from your own middleware validates the key, deducts a credit from the customer’s pool, and records the request. This guide gets you from zero to a working validation in five steps.

See the whole thing first

01 / 07

Set up

dashboard / new project

Project name

Acme…

Create project

Project created

your root_key

reqkey_7Fq3kLm9Za2X

Send this in the header of almost every request.

Create your project

One click in the dashboard. You get a root_key.

The complete ReqKey cycle, one scene at a time — use the arrows or your ← → keys, or tap ⤢ for full screen. Prefer reading? Everything below spells it out.

The mental model

Everything hangs off a project, addressed by a secret rootKey. Under it live your APIs, optional plans, and your consumers. The one idea worth remembering: credits belong to the consumer, not the key. Every key a consumer owns draws from the same shared pool.

resource hierarchy

customer
└─ project            reqkey_live_…        ← your workspace (root key)
   ├─ apis            PaymentAPI, …        ← the services you meter
   ├─ plans           Starter, Enterprise  ← reusable credit templates
   └─ consumers       Acme Corp            ← your customer · owns the credits
      └─ keys         prod_a1b2…           ← auth tokens · share the pool

How validation works

You don’t route customer traffic through ReqKey. Instead, your API calls POST /key/validate before your handler runs. In one round-trip ReqKey confirms the key is real, active, in-scope for the API, and has credits — then deducts from the consumer’s pool and returns a requestId. Your code decides what happens next; optionally POST the response detail to /ingest for analytics.

One credential

Every endpoint authenticates with your project rootKey as a Bearer token. You get it from the dashboard — create a project, open its Settings, and copy the root_key (creating and listing projects is dashboard-only for now). See Authentication.

Quickstart

Base URL: https://api.reqkey.com. Every management call is a POST with a JSON body. Swap in your own secrets as you go.

Create a project

Done in the dashboard — grab the root_key from the project’s Settings. You’ll use it as a Bearer token everywhere else.

Dashboard

# 1 · Create a project — in the dashboard (no API call)
#
#    Dashboard → New project → Settings → copy the root_key
#
#    root_key: reqkey_A1B2C3D4E5F6G7H8I9J0K1L2
#    ↳ your Bearer token for every call below

Register an API

Each API you meter gets an apiId that keys can be scoped to.

Terminal

# 2 · Register an API you want to meter
curl -X POST "https://api.reqkey.com/api/create" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"apiName": "PaymentAPI"}'
# → { "apiId": "api_payment...", "apiName": "PaymentAPI" }

Create a consumer with credits

The consumer owns the credit pool. Pass a credits object, a planId, or neither (unlimited).

Terminal

# 3 · Create a consumer — this is where credits live
curl -X POST "https://api.reqkey.com/consumer/create" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "credits": {"limit": 5000}}'
# → { "consumerId": "cons_xxx..." }

Mint a key

Keys are auth tokens only — they carry no credits of their own.

Terminal

# 4 · Mint a key for the consumer (shares the consumer's pool)
curl -X POST "https://api.reqkey.com/key/create" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"consumerId": "cons_xxx...", "allowedApis": ["api_payment..."]}'
# → { "key": "reqkey_xxx...", "keyId": "key_xxx..." }

Validate on every request

Call this from your middleware. A credit is deducted from the consumer’s pool on success.

Terminal

# 5 · Validate on every request — from your own middleware
curl -X POST "https://api.reqkey.com/key/validate" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"key": "reqkey_xxx...", "apiId": "api_payment..."}'
# → { "valid": true, "creditsRemaining": 4999, "creditsLimit": 5000 }