ReqKeydocs
API reference

Consumers

A consumer represents one of your customers and owns a single credit pool shared by all of its keys. This is where credits — and rate limits — live.

POST/consumer/createBearer

Create consumer

Consumers own credits. Configure credits three ways, in priority order: direct credits object > plan inheritance (planId) > nothing (unlimited). Every key you create under this consumer draws from the same pool. A consumer can also carry a rateLimit that caps how fast all of its keys can call /key/validate.

Body
namestring

Consumer name.

creditsobject

Direct credit configuration (takes priority over plan).

limitnumber

Total credit limit (pool size).

shadowLimitnumber

Warning threshold before the hard limit.

refillobject

Auto-refill: { interval, amount }.

overageobject

Overage: { enabled, limit }.

expiresAtnumber

Credit expiration timestamp (ms).

planIdstring

Inherit credits from a plan (used only if credits is omitted).

rateLimitobject

Request rate limit shared by all the consumer’s keys: limit /key/validate requests per window seconds.

limitnumberrequired

Max requests per window. 1 – 1,000,000,000.

windownumber

Window length in seconds, 1 – 86,400. Default 1. E.g. 100/minute is { limit: 100, window: 60 }.

tagsarray

Array of string tags.

webhookUrlstring

Webhook URL for notifications.

metadataobject

Arbitrary custom metadata.

imageUrlstring

Consumer avatar URL.

externalIdstring

Your system’s identifier for this consumer.

statusstring

Status. Default "active".

Request
curl -X POST "https://api.reqkey.com/consumer/create" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Corporation",
  "credits": {
    "limit": 5000,
    "shadowLimit": 500,
    "overage": {
      "enabled": true,
      "limit": 200
    }
  },
  "rateLimit": {
    "limit": 100,
    "window": 60
  },
  "tags": [
    "enterprise",
    "priority"
  ],
  "externalId": "acme_12345"
}'
Response
{
  "consumerId": "cons_A1B2C3D4",
  "projectKey": "reqkey_xxx...",
  "createdAt": "2026-01-30T12:34:56Z",
  "status": "active",
  "name": "Acme Corporation",
  "tags": [
    "enterprise",
    "priority"
  ],
  "externalId": "acme_12345"
}
  • Omit both credits and planId to give the consumer (and all its keys) unlimited usage.
  • The rate limit is independent of credits — a consumer with unlimited credits can still be rate-limited.
  • If you pass planId and no explicit rateLimit, the consumer inherits the plan’s rate limit; an explicit rateLimit in the same request wins.
  • The consumer is added to the project:{rootKey}:consumers set.
Errors
400Body parse error or invalid rateLimit (limit 1 – 1,000,000,000; window 1 – 86,400 seconds)
401Missing or invalid authentication
500Temporary internal error — safe to retry
POST/consumer/updateBearer

Update consumer

Update any consumer field, including credits and rateLimit. Consumer status doubles as a master switch: set it to "disabled" and every key under the consumer stops validating without touching each key’s own status — ideal for payment failures.

Body
consumerIdstringrequired

Consumer ID to update.

namestring

New consumer name.

statusstring

New status (e.g. "active", "disabled").

planIdstring

New plan ID.

tagsarray

New tags array.

metadataobject

New metadata object.

webhookUrlstring

New webhook URL.

imageUrlstring

New image URL.

externalIdstring

New external ID.

expiresAtstring

Expiration timestamp.

creditsobject

Update credit configuration.

limitnumber

New credit limit (pool size).

usednumber

Set the used count — handy for plan downgrades (reset to 0 for a fresh pool).

shadowLimitnumber

Warning threshold.

overageobject

Overage config: { enabled, limit }.

refillobject

Auto-refill config.

expiresAtnumber

Credit expiration timestamp (ms).

rateLimitobject | null

New rate limit for the consumer, or null to remove it entirely.

limitnumberrequired

Max /key/validate requests per window. 1 – 1,000,000,000.

windownumber

Window length in seconds, 1 – 86,400. Default 1.

Request
curl -X POST "https://api.reqkey.com/consumer/update" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "consumerId": "cons_A1B2C3D4",
  "credits": {
    "limit": 10000,
    "shadowLimit": 1000,
    "overage": {
      "enabled": true,
      "limit": 500
    }
  },
  "rateLimit": {
    "limit": 100,
    "window": 60
  }
}'
Response
{
  "consumerId": "cons_A1B2C3D4",
  "name": "Acme Corporation",
  "status": "active",
  "credits": {
    "limit": 10000,
    "shadowLimit": 1000,
    "overage": {
      "enabled": true,
      "limit": 500
    }
  },
  "keysRestored": 0
}
  • Disabled consumer blocks all its keys; setting it back to "active" re-enables them instantly.
  • Moving status from "deleted" to "active" restores soft-deleted keys (see keysRestored).
  • Downgrading a plan? Pass credits.used: 0 alongside the new limit so remaining never goes negative.
  • rateLimit: null removes the limit — even if the consumer is on a plan that has one. Re-attach the plan (or set a value) to restore it.
  • Changing planId without passing rateLimit re-inherits the new plan’s rate limit; an explicit rateLimit (or null) in the same request wins. A plan with no rate limit leaves the consumer’s current limit alone.
  • Rate-limit changes reach the validation hot path within ~200ms for active consumers (worst case ~30s for a consumer idle longer than 2 minutes).
Errors
400Missing consumerId or invalid rateLimit
403Consumer does not belong to this project
404Consumer not found
500DO request failure
POST/consumer/detailsBearer

Get consumer details

Fetch a consumer with full credit status.

Body
consumerIdstringrequired

Consumer ID to retrieve.

Request
curl -X POST "https://api.reqkey.com/consumer/details" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "consumerId": "cons_A1B2C3D4"
}'
Response
{
  "consumerId": "cons_A1B2C3D4",
  "projectKey": "reqkey_xxx...",
  "name": "Acme Corporation",
  "imageUrl": null,
  "externalId": "acme_12345",
  "metadata": {
    "tier": "enterprise"
  },
  "webhookUrl": "https://acme.com/webhooks/credits",
  "status": "active",
  "planId": "plan_enterprise",
  "tags": [
    "enterprise",
    "priority"
  ],
  "createdAt": "2026-01-30T12:34:56Z",
  "expiresAt": null,
  "updatedAt": "2026-01-30T12:35:00Z",
  "rateLimit": {
    "limit": 100,
    "window": 60
  },
  "credits": {
    "limit": 10000,
    "remaining": 8500,
    "used": 1500,
    "shadowLimit": 1000,
    "overage": {
      "enabled": true,
      "limit": 500
    },
    "refill": {
      "interval": "month",
      "amount": 5000,
      "nextRefillAt": 1743465600000
    },
    "expiresAt": null
  }
}
  • credits is null when the consumer has no credit configuration (unlimited).
  • rateLimit is null when no rate limit is configured.
Errors
400Missing consumerId
403Consumer does not belong to this project
404Consumer not found
POST/consumer/listBearer

List consumers

Returns one page of consumers. All request fields are optional — an empty body returns the first page, newest first. Filters compose (AND): search + status + planId narrow the same result set, and the response reports both the project-wide total and the filtered count.

Body
pagenumber

Page number, 1-based. Default 1.

limitnumber

Page size. Default 25, max 200.

searchstring

Case-insensitive substring match on consumerId OR name.

planIdstring

Filter consumers by plan ID (exact match).

statusstring

Filter by status, e.g. active, deleted (exact match).

sortBystring

createdAt (default), name, status, creditsUsed, or creditsRemaining.

sortOrderstring

asc or desc. Default desc.

Request
curl -X POST "https://api.reqkey.com/consumer/list" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "search": "acme",
  "status": "active",
  "planId": "plan_enterprise",
  "sortBy": "creditsRemaining",
  "sortOrder": "asc",
  "page": 1,
  "limit": 50
}'
Response
{
  "total": 1426,
  "filtered": 2,
  "page": 1,
  "limit": 25,
  "totalPages": 1,
  "sortBy": "createdAt",
  "sortOrder": "desc",
  "consumers": [
    {
      "consumerId": "cons_A1B2C3D4",
      "name": "Acme Corporation",
      "imageUrl": "https://example.com/acme.png",
      "planId": "plan_enterprise",
      "createdAt": "2026-01-30T12:34:56Z",
      "status": "active",
      "apiKeyCount": 2,
      "credits": {
        "limit": 10000,
        "used": 1500,
        "remaining": 8500,
        "refill": {
          "nextRefillAt": 1787003022920
        }
      }
    },
    {
      "consumerId": "cons_X9Y8Z7",
      "name": "Beta Inc",
      "imageUrl": null,
      "planId": null,
      "createdAt": "2026-01-29T10:00:00Z",
      "status": "active",
      "apiKeyCount": 1,
      "credits": null
    }
  ]
}
  • total is the number of consumers in the project; filtered is the count after filters; totalPages = ceil(filtered / limit).
  • credits shows the consumer’s pool (limit, used, remaining) and is null for unlimited consumers.
  • credits.refill.nextRefillAt (epoch ms) is present when the consumer has a scheduled refill.
  • Ordering ties break on consumerId, so pagination is stable across requests.
  • A page past the end returns an empty consumers array (not an error).
Errors
400Invalid sortBy or sortOrder value
401Missing or invalid authentication
POST/consumer/keysBearer

List consumer keys

List a consumer’s keys with the shared credit balance.

Body
consumerIdstringrequired

Consumer ID.

Request
curl -X POST "https://api.reqkey.com/consumer/keys" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "consumerId": "cons_A1B2C3D4"
}'
Response
{
  "consumerId": "cons_A1B2C3D4",
  "credits": {
    "limit": 10000,
    "remaining": 8500,
    "used": 1500
  },
  "total": 2,
  "keys": [
    {
      "keyId": "key_X1Y2Z3",
      "key": "PaymentAPI_A1B2C3D4E5F6G7H8I9J0K1L2",
      "status": "active",
      "createdAt": "2026-01-30T12:34:56Z",
      "allowedApis": [
        "api_payment",
        "api_analytics"
      ]
    },
    {
      "keyId": "key_A9B8C7",
      "key": "PaymentAPI_M1N2O3P4Q5R6S7T8U9V0W1X2",
      "status": "active",
      "createdAt": "2026-01-29T10:00:00Z",
      "allowedApis": [
        "*"
      ]
    }
  ]
}
  • Credits are shown once at the consumer level — all keys share the same pool.
Errors
400Missing consumerId
403Consumer does not belong to this project
404Consumer not found
POST/consumer/deleteBearer

Delete consumer

Soft (7-day recovery) or hard delete a consumer.

Body
consumerIdstringrequired

Consumer ID to delete.

permanentboolean

false = soft delete (default), true = hard delete.

Request
curl -X POST "https://api.reqkey.com/consumer/delete" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "consumerId": "cons_A1B2C3D4",
  "permanent": false
}'
Response
{
  "consumerId": "cons_A1B2C3D4",
  "deleted": true,
  "permanent": false,
  "deletedAt": "2026-01-30T12:34:56Z",
  "keysAffected": 3,
  "message": "Consumer soft deleted. Recoverable within 7 days."
}
  • Soft delete also soft-deletes every key under the consumer (recoverable 7 days).
  • Hard delete removes the consumer, its keys, and its credit state permanently.
Errors
400Missing consumerId
403Consumer does not belong to this project
404Consumer not found
PreviousPlansNext Keys