Customer Portal Walkthrough

The self-service portal for end-user customers at /portal: account setup, two-factor authentication, usage and balance, invoices, reloads, and API documentation.

Audience: your API customers. For the company side see ACCOUNTING.md and USER-MANAGEMENT.md.

1. Create your account

Open http://<host>:<port>/portal and choose Create an account.

Name, email, and a password of at least 8 characters.
You start on the Free plan and get an API key immediately.
If the company already created an account for you (you received an API key by email), sign up with the same email address — your existing account, plan, and API key are kept and the password you choose is attached to it.

Sign-in afterwards is email + password on the same screen.

2. Dashboard

Usage this month — gross usage since the 1st (UTC).
Included credit — how much of your plan's monthly credit was consumed.
Billable — what exceeds the credit (what you'd be invoiced today).
Prepaid balance — funds available for automatic invoice payment.
Your API key — copy it, or regenerate it. Regenerating invalidates the old key immediately; use it as the x-api-key header.

3. Usage & pricing

The API & pricing tab shows the live rate card (free / fixed / variable per endpoint, with size-based pricing for storage) and every plan's multiplier and monthly credit — the same numbers the server bills from.

The interactive API reference (Swagger UI) is linked at the top (/docs).

4. Invoices

Your invoice history with status (draft, issued, paid), totals, credit, amount due, and due date. View / print opens a print-ready invoice — use the browser's Print → Save as PDF for a copy.

Only your own invoices are visible; other customers' ids return "not found".

5. Billing: reloads & email invoicing

Reload balance — add $1–$10,000. Your prepaid balance is drawn down automatically when an invoice is issued: if it fully covers the amount due, the invoice is paid instantly.
Email invoicing — receive a copy of each new invoice by email.

6. Security: two-factor authentication

On the Security tab, click Set up 2FA:

Scan the QR code with any authenticator app (or type the secret manually).
Enter the 6-digit code it shows to enable 2FA.

From then on, sign-in requires the password and the current code. You can disable 2FA with a valid code from the same tab. Sessions expire after 7 days.

Portal API reference

Session-based (Authorization: Bearer <token> from signup/login):

POST /portal/api/signup · POST /portal/api/login · POST /portal/api/logout
GET /portal/api/me · POST /portal/api/api-key
GET /portal/api/usage · GET /portal/api/pricing
GET /portal/api/invoices · GET /portal/api/invoices/:id[?format=html]
POST /portal/api/2fa/setup|enable|disable
POST /portal/api/reload · PUT /portal/api/email-invoicing

Security notes: passwords are stored as scrypt hashes; TOTP secrets are only shown during setup; no hash or secret is ever returned by the API.

3.5 KiB Raw Blame History Unescape Escape