Personal, self-hosted integration. This page is a local reference; the full setup guide is in the repository README.
/api/v1/… route needs
Authorization: Bearer <API_BEARER_TOKEN>. /health and /ready are public.
Never put the token in a URL or share it.
| Method | Path | Purpose |
|---|---|---|
| GET | /health | Liveness: {"status":"ok"} |
| GET | /ready | Readiness and whether a Lebara session is available |
| GET | /api/v1/auth/status | Safe session status; add ?refresh=true to verify upstream |
| POST | /api/v1/auth/start | Start the supported login flow (credentials must be in the service environment) |
| GET | /api/v1/numbers | Numbers available to the account |
| GET | /api/v1/usage?msisdn=…&refresh=false | Current usage snapshot |
| GET | /api/v1/usage/history?msisdn=…&start_date=YYYY-MM-DD | Monthly activity history |
| GET | /api/v1/usage/daily?msisdn=…&days=14 | Daily data derived from local samples |
| POST | /api/v1/usage/refresh | Refresh one number ({"msisdn":"…"}) or all known numbers |
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8686/api/v1/numbers
curl -s -H "Authorization: Bearer $TOKEN" \ "http://127.0.0.1:8686/api/v1/usage?refresh=true"
curl -s -H "Authorization: Bearer $TOKEN" \ "http://127.0.0.1:8686/api/v1/usage/history?start_date=2025-01-01"
curl -s -H "Authorization: Bearer $TOKEN" \ "http://127.0.0.1:8686/api/v1/usage/daily?days=14"
{"error":{"code":"reauth_required","message":"The Lebara session is missing or has expired."}}
Codes include unauthorized, reauth_required, invalid_msisdn,
invalid_date, invalid_parameter, rate_limited,
upstream_timeout, upstream_error, upstream_schema_changed,
and login_challenge_required.
Start the login with:
curl -s -X POST -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8686/api/v1/auth/start
If Lebara presents a Cloudflare/Turnstile challenge, complete it in the visible Chromium window
(run with BROWSER_HEADLESS=false). The service never defeats or bypasses a challenge.
Current-plan data is normalised to decimal GB (1 GB = 1000 MB). Voice is minutes, SMS is messages.
History data rows are reported upstream in MB and include both value (MB) and value_gb.
Unlimited allowances keep unlimited: true; numeric totals are included only when upstream supplies them.
The upstream activity history is monthly only. /usage/daily is derived from
optional local samples; a new installation cannot reconstruct days before sampling began.