# 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**.

![Sign up](screenshots/portal-signup.png)

- 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.

![Sign in](screenshots/portal-login.png)

---

## 2. Dashboard

![Dashboard](screenshots/portal-dashboard.png)

- **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.

![API & pricing](screenshots/portal-docs.png)

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

## 4. Invoices

![Invoices](screenshots/portal-invoices.png)

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.

![Printable invoice](screenshots/portal-invoice-html.png)

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

## 5. Billing: reloads & email invoicing

![Billing](screenshots/portal-billing.png)

- **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**:

![2FA setup](screenshots/portal-2fa-setup.png)

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.