98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
# 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.
|