Authentication

ZPBX uses Bearer token authentication for all API requests. Every request must include your API key in the Authorization header.

API keys

API keys are generated from the ZPBX console → Management → API v1 Keys. Each key:

• Starts with zpbx_ (e.g. zpbx_a1b2c3d4e5f6...)
• Is scoped to a billing group (tenant isolation) — or platform-wide if no group is assigned
• Is stored hashed (SHA-256) — the full key is shown only once at creation and cannot be recovered
• Can be revoked at any time
• Has no expiry by default (you can set one)
• Supports granular scopes (e.g. calls:read, numbers:read, balances:read)

Using your API key

Include the key in every request:

curl https://api.zpbx.es/v1/calls \
  -H "Authorization: Bearer zpbx_your_api_key_here"

JavaScript example

const res = await fetch("https://api.zpbx.es/v1/calls?pageSize=10", {
  headers: {
    "Authorization": `Bearer ${process.env.ZPBX_API_KEY}`,
  },
})
const data = await res.json()

Python example

import requests

response = requests.get(
    "https://api.zpbx.es/v1/calls",
    params={"pageSize": 10},
    headers={"Authorization": f"Bearer {api_key}"},
)
data = response.json()

Scopes

Each API key has a set of scopes that determine which endpoints it can access:

Scope	Access
accounts:read	List accessible billing groups
calls:read	Retrieve call detail records
calls:read_cost	Include buy cost, margin, supplier in call records
numbers:read	List provisioned numbers
balances:read	Check account balance
rates:read	Look up rates for a destination
messages:read	List SMS records

Default scopes for a new key: accounts:read, calls:read, numbers:read, rates:read, balances:read.

Error responses

Errors use RFC 7807 Problem Details with numeric codes:

Code	HTTP	Cause
20001	401	Missing Authorization header
20003	401	Invalid API key
20004	401	Expired API key
20005	401	Disabled API key
20006	403	Insufficient scope for this endpoint
42901	429	Rate limit exceeded — check Retry-After header

Every error includes a requestId — include it when contacting support.

Tenant scoping

API keys are automatically scoped to the billing group they belong to:

• Customer keys — only see their own CDRs, numbers, and balance
• Reseller keys — see their data + child billing groups
• Platform keys (no billing group) — full access to all data

This means a customer can never access another customer's data, even if they guess the URL.

Rate limiting

API keys are limited to 100 requests per minute by default. When exceeded, the API returns 429 with:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718601660
Retry-After: 42