API Reference

Authentication

How to authenticate requests to the Beliq API using API keys.

All /v1/* endpoints require an API key. If a key is missing, the API returns 401 AUTHENTICATION_REQUIRED.

Obtaining an API key

Sign in to the Beliq dashboard
Navigate to Settings → API Keys
Click Create API Key and give it a descriptive label
Copy the key immediately — it is only displayed once

API keys are stored securely in hashed form. Beliq does not store or log your plaintext key.

Passing the API key

Use one of two methods:

Authorization header (recommended)

Authorization: Bearer YOUR_API_KEY

X-API-Key header

X-API-Key: YOUR_API_KEY

Both methods work the same way. Use whichever is easier in your client.

Example request

validate.sh

curl -X POST https://api.beliq.eu/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

Verifying a key

GET /v1/me returns the account, plan, and live quota for the calling key. It is a lightweight credential check that does not count against your monthly quota, so it is the right call for “is this key valid?” probes. The official connectors and SDKs use it to validate stored credentials.

me.sh

curl https://api.beliq.eu/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "keyId": "ak_3f9c2a1b8e",
  "keyPrefix": "blq_live_3f9c",
  "org": { "id": "org_7b2e9d", "name": "Acme AG" },
  "plan": { "id": 3, "name": "Growth" },
  "rateLimitPerMinute": 200,
  "quota": { "limit": 10000, "used": 1234, "remaining": 8766, "resetsAt": "2026-07-01T00:00:00.000Z" }
}

resetsAt is the first instant of the next UTC month. A 401 or 403 here means the key is missing, malformed, or revoked (see the table below).

Error responses

HTTP Status	Error Code	Meaning
401	`AUTHENTICATION_REQUIRED`	No API key was provided, or the key format is invalid
403	`INVALID_API_KEY`	The API key does not exist or has been revoked
429	`QUOTA_EXCEEDED`	Your monthly usage quota is exhausted — upgrade your plan
429	`RATE_LIMITED`	Too many requests in the current rate-limit window — back off and retry

Quotas and rate limits

Beliq applies request limits to keep the service reliable and fair for all customers.

Throttle	Window	Source of truth	429 error code
Monthly quota	Calendar month (UTC)	`subscriptionPlans.monthlyQuota` (per plan)	`QUOTA_EXCEEDED`
Per-minute burst	Rolling 1-minute window	Plan-based rate limit	`RATE_LIMITED`
Abuse throttle	Temporary protection window	Beliq runtime	`RATE_LIMITED`

Quota and rate limits are tracked per account. All API keys belonging to the same account share the same quota and burst limit.

Mid-month plan changes: once usage is recorded for a calendar month, the stored monthly limit for that month stays fixed until the next UTC month (or operator adjustment). Upgrading a subscription updates the plan for new periods; it does not automatically raise the cap already stored for the current month’s usage row.

QUOTA_EXCEEDED includes your current usage in the message (for example "Monthly quota exceeded (1000/1000)"). Check usage in the dashboard or upgrade your plan.

Response headers

Header	Set on	Meaning
`x-ratelimit-limit`	All `/v1/*` responses	Your plan’s request limit for the current minute
`x-ratelimit-remaining`	All `/v1/*` responses	Burst budget left in the current minute
`x-ratelimit-reset`	All `/v1/*` responses	Seconds until the burst window resets
`Retry-After`	All `/v1/*` 429 responses	Seconds to wait before retrying. For `RATE_LIMITED` this is the seconds left in the burst window (or in the abuse-throttle TTL); for `QUOTA_EXCEEDED` this is the seconds until the next UTC calendar month begins

Always honor Retry-After when present. It indicates the earliest safe retry time.

Prometheus metrics (operators)

When enabled for your deployment, GET /metrics may include a counter beliq_api_http_429_total labeled by throttle subtype (rate_limit_hit, quota_exhausted, abuse_throttle_hit, unknown), and a histogram beliq_api_http_request_duration_seconds (method, route) for request latency — useful for alerting and SLO dashboards.

Beliq also sends common browser hardening headers (for example X-Content-Type-Options, X-Frame-Options) on API responses; they do not replace your own security review for embedded contexts.

Default per-minute limits by plan

These are the default request-per-minute limits by plan.

Plan	Rate limit per minute
Free	10
Starter	100
Growth	200
Business	300
Enterprise	500

See pricing for the monthly document quota included with each plan (Free, Starter, Growth, Business, Enterprise).

Key management

Revoke a key at any time from the dashboard. Revoked keys return INVALID_API_KEY immediately.
Rotate keys by creating a new key, updating your integration, then revoking the old key.
Multiple keys are supported — use separate keys for different environments or services.