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:

1. Scan the QR code with any authenticator app (or type the secret manually).
2. 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.