HTTP Tweak
These routes support the first-party mobile app and platform callbacks. They use device signing or provider authentication, separate from Client and Business API keys. This page maps the current flows so backend integrators know which API owns each operation.
For backend configuration automation, start with the Client quickstart or Business generation. A device request requires the app's signing and encryption implementation; a static bearer key is insufficient.
Device bootstrap
All paths in the following tables include the /api prefix.
| Method and path | Input / purpose |
|---|---|
POST /api/v1/device/register |
Encrypted device_id, current app ver, and pubkey_hash; binds a device to its signing key and platform |
GET /api/v1/challenge |
Encrypted device_id and ver query fields; returns a short-lived nonce |
POST /api/v1/integrity/challenge |
ver, optional encrypted device_id, action, and client_key_hash; starts the Android integrity exchange |
POST /api/v1/integrity/verify |
challenge, request_data, ver, device/key binding, and an integrity_token when enabled; returns integrity session information |
Use X-Platform: android or X-Platform: ios consistently with registration. The signed platform claim must match the registered device. Minimum app versions are enforced by the installation.
Signed requests
The app signs a fresh ES256 JWT using its device key and sends it as Authorization: Bearer …. The current device flow embeds the public key in pk, binds it to the registered hash, and binds request data to a one-time challenge. The encrypted device identity is carried in sub; ver identifies the app version. Configuration-scoped operations also use a signed cfg claim.
Sign the exact request body you send. Changes in JSON whitespace or serialization after signing can invalidate the body binding. Each retry needs the appropriate fresh signing/challenge flow. A nonce may already have been consumed when later middleware rejects the request.
Signed app routes have a trusted per-device rate limiter after signature verification. Android /config and /config/protected_import also apply the installation's Play Integrity session policy using X-Play-Integrity-Session. Verified iOS requests use the device-signature flow without Google Play Integrity.
Configuration access and delivery
All these routes use POST and signed device authentication.
| Path | Purpose |
|---|---|
/api/v1/auth/password |
Verify configuration password access using signed password claims |
/api/v1/auth/hwid |
Verify configuration device access |
/api/v1/config |
Fetch configuration content; applies integrity policy and access checks |
/api/v1/config/status |
Read whether the device is blocked for a configuration; remains accessible to blocked devices |
/api/v1/config/update |
Check configuration update information |
/api/v1/config/server |
Retrieve an eligible server using configuration and server identity |
/api/v1/config/export |
Upload exported configuration content and receive a share link |
/api/v1/config/import |
Resolve a share identifier or supported configuration link |
/api/v1/config/protected_export |
Store protected-export material bound to the signed configuration key |
/api/v1/config/protected_import |
Retrieve protected-export material; applies integrity policy |
/api/v1/config/convert |
Convert supported app configuration content; has an additional 6-per-minute limiter |
Configuration access routes apply blocklist checks except /config/status, which must remain readable by blocked devices. Password and HWID authentication can enforce expiration, activation, and one-time-use policies. Response bodies vary by operation: JSON metadata, import text, or encrypted content. They do not share the Client API's response schema.
Subscriptions and telemetry
| Method and path | Purpose |
|---|---|
POST /api/v1/device/subscription |
Signed device request to synchronize Google Play purchase/entitlement state; accepts optional purchase_token and its product_id |
POST /api/v1/device/apple-subscription |
Signed device request to synchronize Apple subscription state |
POST /api/v1/analytics/events |
Signed event batch; returns HTTP 202 with accepted/dropped counts |
GET /api/v1/mobile-promotions |
Public campaign metadata; requires platform and app_version |
GET /api/v1/mobile-promotions/{promotion} |
Public metadata for one eligible campaign; same platform/version inputs |
POST /api/v1/mobile-promotions/{promotion}/events |
Signed campaign interaction with event and revision |
Public promotion responses expose metadata rather than raw campaign HTML. Analytics batching and enabled events follow installation settings.
Provider callbacks
| Method and path | Authentication |
|---|---|
POST /api/telegram/webhook |
Telegram webhook secret header |
POST /api/google-play/rtdn |
Google-signed OIDC bearer token for the Pub/Sub push |
POST /api/apple/notifications |
Apple signed notification payload |
These endpoints are callbacks configured by the platform operator. Client and Business keys do not authenticate them. Google Play callbacks have a route limit of 120 per minute and Apple callbacks 60 per minute, in addition to the applicable general API limiter.
Account utility
GET /api/user is protected by Sanctum and returns the authenticated user. It is separate from the Client API credential flow; use GET /api/v1/configs to verify a Client API integration.