Accounts, permissions, and secrets

A customer login, a backend API key, a proxy password and a webhook signing secret protect different interfaces. Keep them separate. A backend key uses its owner’s account permissions; it does not grant a reseller superuser privileges.

Choose the account that performs the action

Action	Required account context
Read or buy your own package	Authenticated account with the required feature enabled; sub-users cannot create invoices
Manage customers and allocate shared quotas	Parent reseller with its own root order for the selected package
Create an independent user or set invoice status=paid	Superuser; invoice user_id additionally requires the caller’s reseller flag
Create, modify or delete coupons	Staff account, not an ordinary reseller
Read customer resources	Within the endpoint’s ownership scope; a filter does not grant access

Use a privileged service key only in your backend. Your backend must authorize the local customer before resolving and sending their ProxyRequest IDs. Do not pass a global service key through to the browser.

Sign in with a password or Google

POST /signup creates an account when registration is enabled. It is different from a reseller’s POST /users provisioning flow. For password login:

{ "email": "{email}", "password": "{account_password}" }

Send this to POST /login. A completed login returns 200 with token and refresh. Use token as Authorization: Bearer …; call /refresh using its documented request shape before the session expires. Store tokens according to your application’s security model and never log them.

When MFA is required, login returns 202 with status: "otp_required", a short-lived challenge and expires_in. That is not an authenticated token pair. Send the returned challenge and the authenticator code to /login/otp:

{ "challenge": "THE_CHALLENGE_FROM_LOGIN", "code": "492031" }

The Google-login operation accepts the identity credential defined in its reference. Handle the documented token/challenge outcome rather than assuming Google login bypasses MFA. Password recovery uses /recover-password; it is not the proxy-password reset endpoint.

Enroll and manage two-factor authentication

1. Read GET /profile/2fa/status.
2. Start POST /profile/2fa/setup with the required account proof (password, or the supported Google credential for a passwordless account).
3. Show the returned QR/otpauth_url securely to the account owner. The secret is sensitive setup material.
4. Confirm an authenticator code through /profile/2fa/confirm; setup alone does not prove enrollment is complete.
5. Re-read status. Replacing or disabling an existing authenticator requires the proofs documented by setup/disable; do not build a bypass in your UI.

Use a fresh challenge after an expired or consumed login challenge. Apply bounded retries to safe reads, and reconcile the authentication state before repeating an uncertain write.

Profile and account lifecycle

GET /profile returns the current account. PATCH /profile changes supported profile fields; preserve its ETag and use If-Match to avoid losing a concurrent edit. Use /profile/change-password for the account login password, not proxy credentials. Follow its validation and MFA requirements.

DELETE /profile deletes the authenticated account. Do not offer it as logout, subscription cancellation or a refund. Require explicit confirmation in your application, stop new commercial activity and retain the mappings needed for your own accounting before deletion.

For another user’s details and policy, use the managed user lifecycle rather than pretending /profile targets an arbitrary customer.

Create and rotate backend API keys

Use POST /api-keys with the key title and allowed-IP settings supported by the reference. Save the returned full secret immediately. GET /api-keys is an inventory surface, not a secret-recovery mechanism. Do not invent per-key capability scopes beyond the schema; account ownership and source-IP restrictions still matter.

Rotation sequence: create a replacement → store it securely → deploy and verify reads → finish or reconcile in-flight writes on the old key → revoke the old key with DELETE /api-keys/{id}. Do not repeat an uncertain write merely because the replacement key is active.

Rotate proxy credentials

For an allowed order, POST /reset-password accepts order_id and returns a success message, not the new secret. Re-read the order or generate credentials afterward. For a managed user, POST /users/{id}/password requires package_id to select the order whose proxy password you want to rotate. Both are separate from account password recovery and can have cooldown restrictions.

Deploy the replacement proxy password to every affected worker. A password change is not a durable cancellation policy: a still-authorized customer may obtain new credentials.

Session management is unavailable

GET /sessions and DELETE /sessions/{id} currently return 403 for authenticated callers because ownership cannot be verified. They are not a working “sign out another device” feature. Sticky proxy generation remains available; see sticky sessions.

Connect Telegram

1. Read GET /integrations/telegram/connection to show current connection state.
2. Call POST /integrations/telegram/link and direct the account owner to its short-lived bot_url before expires_at.
3. After the official bot completes linking, refresh connection state; do not assume creating a link means it was consumed.
4. Use PATCH /integrations/telegram/connection for documented notification preferences and DELETE to disconnect.

Bot-side link consumption and session endpoints are trusted internal services, not part of your public integration. Keep link URLs out of logs.

Load deployment information

Read GET /settings for the authenticated deployment’s supported runtime values, such as gateway information, thresholds and currencies. Do not hard-code another deployment’s settings or treat their presence as authorization. GET /news supplies paginated customer announcements; render it as content, not a provisioning control signal.

See the complete operation map for exact request bodies and response variants, and reliable requests for guarded writes.