API usage

Authentication

Every request to the data plane carries an org API key:

Authorization: Bearer recurfy_sk_...

Create keys from the dashboard API keys tab. Treat them like secrets; prefer calling Recurfy from your backend, not from a public browser bundle.

Track usage

The primary write path is POST /v1/track. Example:

curl -s http://localhost:4000/v1/track \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user-1",
    "entitlementKey": "api_calls",
    "quantity": 1
  }'

Typical fields:

Field	Description
externalUserId	Your product’s stable user identifier.
entitlementKey	Matches an entitlement you defined in the dashboard.
quantity	How much usage to record (default 1).

The response includes whether the call is allowed and updated remaining / limit style fields where applicable (exact shape depends on your schema and version).

Errors

• 401 — missing or invalid API key.
• 4xx — validation or business-rule errors (unknown entitlement, etc.).
• 5xx — server errors; use idempotent retry strategies where possible.

For local URLs and ports, see Local development.