ReqKey.docs
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 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.

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).

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
    }
  },
  "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 consumer is added to the project:{rootKey}:consumers set.
Errors
400Body parse error
401Missing or invalid authentication
500Temporary internal error — safe to retry
POST/consumer/updateBearer

Update consumer

Update any consumer field, including credits. 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).

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
    }
  }
}'
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.
Errors
400Missing consumerId
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",
  "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).
Errors
400Missing consumerId
403Consumer does not belong to this project
404Consumer not found
POST/consumer/listBearer

List consumers

List consumers, optionally filtered by plan.

Body
planIdstring

Filter consumers by plan ID.

Request
curl -X POST "https://api.reqkey.com/consumer/list" \
  -H "Authorization: Bearer reqkey_xxx..."
Response
{
  "total": 2,
  "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
      }
    },
    {
      "consumerId": "cons_X9Y8Z7",
      "name": "Beta Inc",
      "imageUrl": null,
      "planId": null,
      "createdAt": "2026-01-29T10:00:00Z",
      "status": "active",
      "apiKeyCount": 1,
      "credits": null
    }
  ]
}
  • credits is null for unlimited consumers.
Errors
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