ReqKey.docs
API reference

Keys

Keys are the tokens your customers send. They carry no credits of their own — validation deducts from the consumer pool. /key/validate is the endpoint you call on every request.

POST/key/createBearer

Create key

Keys are authentication tokens only — they have no credits of their own. Every deduction goes to the consumer’s shared pool. Scope a key to specific APIs with allowedApis, or use ["*"] for all.

Body
consumerIdstringrequired

Consumer this key belongs to.

allowedApisarray

API IDs this key can access, or ["*"] for all. Default ["*"].

prefixstring

Custom key prefix (defaults to project name).

tagstring

Optional tag.

metadataobject

Custom metadata.

statusstring

Key status. Default "active".

Request
curl -X POST "https://api.reqkey.com/key/create" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "consumerId": "cons_A1B2C3D4",
  "allowedApis": [
    "api_payment",
    "api_analytics"
  ],
  "prefix": "prod",
  "tag": "production",
  "metadata": {
    "environment": "prod",
    "version": "v2"
  }
}'
Response
{
  "key": "prod_A1B2C3D4E5F6G7H8I9J0K1L2",
  "keyId": "key_X1Y2Z3A4",
  "createdAt": "2026-01-30T12:34:56Z",
  "status": "active"
}
  • Key creation is blocked if the consumer’s status is "disabled" or "deleted".
  • Keep the keyId — you’ll use it to update or reroll the key later.
Errors
400Missing consumerId, consumer disabled/deleted, or body parse error
403Consumer does not belong to this project
404Consumer not found
500Temporary internal error — safe to retry
POST/key/validateBearer

Validate key

Call this from your own middleware on every incoming request. It confirms the key is real, active, in-scope for the API, and has credits — then deducts from the consumer’s shared pool and returns a requestId you can feed into /ingest.

Body
keystringrequired

The API key to validate.

apiIdstring

API to check access against (enforced when the key has restricted allowedApis).

creditsnumber

Credits to deduct. Default 1. Use 0 for a free check.

resourcestring

Resource identifier recorded for analytics.

Validation order
  1. 1Key exists
  2. 2Key belongs to the authenticated project
  3. 3Key status is "active" (not disabled / pending / deleted)
  4. 4Consumer status is "active" (a disabled consumer blocks all its keys)
  5. 5Key has not expired
  6. 6If apiId is given and the key is scoped, the key can access that API
  7. 7Consumer has sufficient credits (skipped when the consumer is unlimited)
Request
curl -X POST "https://api.reqkey.com/key/validate" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "key": "prod_A1B2C3D4E5F6G7H8I9J0K1L2",
  "apiId": "api_payment",
  "credits": 1,
  "resource": "/api/v1/payments"
}'
Response
{
  "valid": true,
  "requestId": "abc123xyz",
  "apiId": "api_payment",
  "apiName": "PaymentAPI",
  "createdAt": "2026-01-30T12:34:56Z",
  "expiresAt": null,
  "creditsRemaining": 9995,
  "creditsLimit": 10000,
  "allowedApis": [
    "api_payment",
    "api_analytics"
  ],
  "resource": "/api/v1/payments"
}
  • Credits are deducted from the consumer’s shared pool, never the key.
  • Non-integer credits are rounded down (2.5 → 2). credits: 0 skips deduction.
  • creditsRemaining and creditsLimit are null for unlimited consumers.
  • Pass the returned requestId to /ingest to attach full request/response logs.
Errors
400Missing key or body parse error
401Missing or invalid project key
402Consumer credit limit exceeded
403Key/consumer disabled, or key lacks access to apiId
POST/key/updateBearer

Update key

Manages key-level properties only. For credit changes use /consumer/update.

Body
keyIdstringrequired

Key ID to update (or pass key instead).

keystring

The API key value (alternative to keyId).

allowedApisarray

Updated allowed API IDs, or ["*"] for all.

rerollKeyboolean

true regenerates the key value (old one dies immediately).

statusstring

New status ("active", "disabled", "pending").

tagstring

New tag.

metadataobject

Updated metadata.

Request
curl -X POST "https://api.reqkey.com/key/update" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "keyId": "key_X1Y2Z3A4",
  "allowedApis": [
    "api_payment",
    "api_analytics",
    "api_billing"
  ],
  "status": "active",
  "rerollKey": true
}'
Response
{
  "key": "prod_N3W4K3Y5V6A7L8U9E0H1E2R3",
  "status": "active"
}
  • rerollKey preserves keyId and all settings — only the key value changes, using the same prefix.
Errors
400Missing both keyId and key
403Key does not belong to this project
404Key not found
500DO request failure
POST/key/detailsBearer

Get key details

Fetch a key with its consumer’s credit state.

Body
keyIdstringrequired

Key ID (or pass key instead).

keystring

The API key value (alternative to keyId).

Request
curl -X POST "https://api.reqkey.com/key/details" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "keyId": "key_X1Y2Z3A4"
}'
Response
{
  "keyId": "key_X1Y2Z3A4",
  "key": "prod_A1B2C3D4E5F6G7H8I9J0K1L2",
  "consumerId": "cons_A1B2C3D4",
  "allowedApis": [
    "api_payment",
    "api_analytics"
  ],
  "status": "active",
  "createdAt": "2026-01-30T12:34:56Z",
  "updatedAt": "2026-01-30T14:00:00.000Z",
  "credits": {
    "limit": 10000,
    "remaining": 9850,
    "used": 150,
    "shadowLimit": 1000,
    "expiresAt": null,
    "refill": {
      "nextRefillAt": 1743465600000
    }
  },
  "tag": "production",
  "metadata": {
    "environment": "prod"
  }
}
  • The credits field is the consumer’s state (null if unlimited), not a per-key balance.
Errors
400Missing both keyId and key
403Key does not belong to this project
404Key not found
POST/key/deleteBearer

Delete key

Soft or hard delete a key. Does not touch consumer credits.

Body
keyIdstringrequired

Key ID (or pass key instead).

keystring

The API key value (alternative to keyId).

permanentboolean

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

Request
curl -X POST "https://api.reqkey.com/key/delete" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "keyId": "key_X1Y2Z3A4",
  "permanent": false
}'
Response
{
  "deleted": true,
  "key": "prod_A1B2C3D4E5F6G7H8I9J0K1L2"
}
  • Soft delete is recoverable for 7 days via consumer update. Deleting a key never frees or changes consumer credits.
Errors
400Missing both keyId and key
403Key does not belong to this project
404Key not found
POST/key/creditsBearer

Get credits

Read the consumer’s current limit and remaining balance via a key.

Body
keystringrequired

API key used to resolve the consumer.

Request
curl -X POST "https://api.reqkey.com/key/credits" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "key": "prod_A1B2C3D4E5F6G7H8I9J0K1L2"
}'
Response
{
  "limit": 10000,
  "remaining": 9850
}
  • Both fields are null when the consumer is unlimited.
Errors
400Missing key
403Key does not belong to this project
404Key not found
POST/key/rechargeBearer

Recharge credits

Add credits to a consumer’s pool (identified by a key).

Body
keystringrequired

API key used to resolve the consumer.

creditsnumberrequired

Credits to add (must be positive).

Request
curl -X POST "https://api.reqkey.com/key/recharge" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "key": "prod_A1B2C3D4E5F6G7H8I9J0K1L2",
  "credits": 5000
}'
Response
{
  "success": true,
  "key": "prod_A1B2C3D4E5F6G7H8I9J0K1L2",
  "consumerId": "cons_A1B2C3D4",
  "previousCredits": 10000,
  "addedCredits": 5000,
  "newTotalCredits": 15000,
  "availableCredits": 14850,
  "allocated": 0,
  "message": "Credits updated instantly"
}
  • Recharge is additive and benefits every key under the consumer.
  • Synced to every region immediately; if a sync is ever missed, it is reconciled within 1 second.
Errors
400Missing key or credits, credits not positive, or key has no consumer
403Key does not belong to this project
404Key not found
PreviousConsumersNext Ingestion