Docs POST /v1/verify

POST /v1/verify

Verify an API key and check remaining quota, plan, and entitlements.

The verify endpoint is the core of Holdify. Call it on every incoming request to:

Check if the API key is valid and active
Get the customer's plan and entitlements
Check remaining quota for rate limiting
Optionally consume units from the quota

Request

POST /v1/verify

http

POST /v1/verify
Authorization: Bearer <project_api_key>
Content-Type: application/json

{
  "key": "hk_live_abc123...",
  "resource": "chat.completions",
  "units": 1
}

Request body

Field	Type	Required	Description
key	string	Yes	The customer's API key to verify
resource	string	No	Resource being consumed (e.g., "api-calls", "chat.completions")
units	integer	No	Units to consume from quota (default: 1)

Response

200 OK - Valid key

Success response

http

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000

{
  "valid": true,
  "remaining": 42,
  "reset_at": "2025-02-01T00:00:00Z",
  "plan": "pro",
  "entitlements": ["chat", "embeddings", "fine-tuning"]
}

200 OK - Invalid key

Note: Invalid keys return 200 with valid: false. This allows you to handle invalid keys without exceptions.

Invalid key response

http

HTTP/1.1 200 OK
Content-Type: application/json

{
  "valid": false,
  "remaining": 0,
  "reset_at": null,
  "plan": null,
  "entitlements": []
}

Response fields

Field	Type	Description
valid	boolean	Whether the key is valid and active
remaining	integer	Remaining quota for the current period
reset_at	string \| null	ISO 8601 timestamp when quota resets
plan	string \| null	Customer's current plan (e.g., "free", "pro", "business")
entitlements	string[]	List of active entitlements/features

Errors

401 Unauthorized

Your project API key is invalid or missing. This is different from verifying an invalid customer key.

401 response

http

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "docs_url": "https://holdify.io/docs/errors#invalid-api-key"
}

Common errors

Code	HTTP	Description
INVALID_API_KEY	401	Project API key is invalid
INVALID_REQUEST_BODY	400	Request body failed validation
RATE_LIMIT_EXCEEDED	429	Too many verify requests

Example

curl

bash

curl -X POST https://api.holdify.io/v1/verify \
  -H "Authorization: Bearer hpk_live_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "hk_live_customer_key",
    "resource": "api-calls",
    "units": 1
  }'

Best practices

Call verify on every request. Don't cache the result client-side. Holdify responses are fast (<50ms) and reflect real-time entitlement changes.
Check remaining before proceeding. If remaining is 0 or negative, return 429 with Retry-After header.
Use entitlements for feature gating. Check entitlements.includes('feature') to gate access to premium features.
Handle gracefully on timeout. If Holdify is unreachable, decide whether to fail open (allow) or fail closed (deny) based on your use case.