GET /api/portal/appointment-requests — the caller's OWN requests, newest first.

Responses

Security: bearer

POST /api/portal/appointment-requests — ask for a slot on a staff member's calendar. The slot must be FULLY inside one free interval of that staff member's PUBLISHED availability (windows minus time-off minus bookings) — requests are intents, so several clients may hold overlapping pending requests; the staff approval is the single point that books the calendar (and re-validates everything).

Request body

PortalCreateAppointmentRequest

Responses

Security: bearer

POST /api/portal/appointment-requests/{id}/cancel — the requester withdraws their own still-pending request. Terminal; decided requests cannot be cancelled here (staff owns the calendar once decided).

Parameters

Request body

PortalCancelRequest

Responses

Security: bearer

GET /api/portal/csat/{token} — validity check for the in-app response view. Scoped TWICE: the survey row must belong to the caller's client, and the token must be live (sent, unexpired). Read-only — rendering the form never burns the single-use token.

Parameters

Responses

Security: bearer

POST /api/portal/csat/{token} — the single-use consume + score record. The consume UPDATE wins exactly once per token; the event (and the audit row) ride the same transaction, so `csat.response_recorded` never fires for a replayed or expired link.

Parameters

Request body

PortalCsatSubmit

Responses

Security: bearer

GET /api/portal/invoices — the caller's client's invoices (issued and paid only), newest issued first.

Responses

Security: bearer

GET /api/portal/invoices/{id} — one of the caller's client's invoices with lines and payment receipts. Another client's document (or a voided one) is a 404, indistinguishable from absent.

Parameters

Responses

Security: bearer

GET /api/portal/invoices/{id}/document — the SAME print-ready HTML document staff print (shared renderer), client-scoped: another client's (or a void) invoice is a plain 404.

Parameters

Responses

Security: bearer

POST /api/portal/invoices/{id}/pay — record a payment through the `PaymentProvider` seam from the portal. v1 resolves the built-in none-mode provider: NOTHING is charged externally; the receipt ("ledger-only") records that the client settled the amount — the UI presents it exactly that way. Provenance: the payment row keeps `created_by = NULL` (portal identities are not staff rows), the audit row and the write trail carry the caller's portal actor kind.

Parameters

Request body

PortalPayRequest

Responses

Security: bearer

GET /api/portal/kb/articles — published client-facing articles (optionally narrowed to one visible category), gated by the effective client-facing rule in the query.

Parameters

Responses

Security: bearer

GET /api/portal/kb/articles/{id} — one client-gated article; a draft, archived, unflagged, or foreign article is a plain 404.

Parameters

Responses

Security: bearer

GET /api/portal/kb/categories — the client-visible category tree.

Responses

Security: bearer

GET /api/portal/kb/search — FTS over client-visible published articles only (websearch query + trigram fallback, ranked the same way the unified search ranks).

Parameters

Responses

Security: bearer

POST /api/portal/login — argon2 verify against `portal_users`. No MFA in portal v1 (documented deferral). Disabled accounts resolve to nothing → uniform 401, never revealing which half failed.

Request body

PortalLoginRequest

Responses

POST /api/portal/magic-link/confirm — spend the link, get portal tokens.

One 401 for unknown, already-used, expired, and disabled alike. The claim itself enforces the standing check (the UPDATE joins `portal_users`), so there is no window between "may this identity sign in?" and "spend it".

Request body

PortalMagicLinkConfirm

Responses

POST /api/portal/magic-link/request — mail a single-use sign-in link.

Throttled per address and per IP on the portal's OWN gate kind, so a run against portal addresses never locks a staff member out of `/api/login`.

Request body

PortalMagicLinkRequest

Responses

GET /api/portal/me — the signed-in portal identity.

Responses

Security: bearer

GET /api/portal/quotes — the caller's client's quotes (non-draft only), newest first.

Responses

Security: bearer

GET /api/portal/quotes/{id} — one quote of the caller's client with its lines. A foreign quote or a draft is a bare 404 (no existence leak).

Parameters

Responses

Security: bearer

POST /api/portal/quotes/{id}/approve — the client accepts a sent quote. Same `sent → accepted` leg as the staff flow; the provider can then run the conversion-to-invoice seam.

Parameters

Request body

PortalQuoteDecisionRequest

Responses

Security: bearer

POST /api/portal/quotes/{id}/decline — the client declines a sent quote. Same `sent → declined` leg as the staff flow; the optional reason is audit-only, never shown back as validation.

Parameters

Request body

PortalQuoteDecisionRequest

Responses

Security: bearer

POST /api/portal/refresh — rotation within the portal session family. A presented token resolves ONLY via its live session row; rotation revokes that row, so replaying an old refresh token fails.

Request body

PortalRefreshRequest

Responses

GET /api/portal/schedule/slots — published availability as FREE intervals per staff member: weekly windows minus time-off minus already-booked time (appointments + on-call). Slots that already started are dropped; anything shorter than 30 minutes is noise.

Parameters

Responses

Security: bearer

GET /api/portal/tickets — the caller's client's tickets across EXPOSED boards only. Unexposed boards are invisible, not empty-filtered.

Parameters

Responses

Security: bearer

GET /api/portal/tickets/{id} — detail plus comments through the notes-taxonomy whitelist for the caller's tier. A ticket from another client (or an unexposed board) is a 404, indistinguishable from absent.

Parameters

Responses

Security: bearer

GET /api/portal/tickets/{id}/attachments — attachments the portal caller may see: ticket-level files always; comment files only when the owning note kind is visible to this tier.

Parameters

Responses

Security: bearer

GET /api/portal/tickets/{id}/attachments/{attachment_id}/download — streams one visible attachment through the API. Hidden or foreign attachments are plain 404s (no existence leak).

Parameters

Responses

Security: bearer

POST /api/portal/tickets/{id}/reply — ALWAYS creates a `client_visible` comment regardless of tier, authored under portal audit provenance (`actor_kind = portal_contact | portal_approver | portal_it_manager`; `author_id` stays NULL because portal identities are not staff rows). Emits the SAME `ticket.comment_added` event as staff replies so every downstream notification path works unchanged.

Parameters

Request body

PortalReplyRequest

Responses

Security: bearer