APIs

MiStorage APIs

One REST API serving three audiences. Every response uses the same envelope, every protected endpoint takes a short-lived bearer token, and refresh happens through an HTTP-only cookie.

Environments

Environment	Base URL	Notes
Local development	`http://localhost:5179`	`dotnet run` (http profile). The https profile adds `https://localhost:7206`.
Interactive reference	`/scalar/v1`	Scalar UI over the OpenAPI document at `/openapi/v1.json`. Development only.
Production	Azure App Service	Reached by the MiStorage frontend; auth calls go through the frontend's same-origin relay (see below).
Health	`GET /api/health` on both	The API's checks its database; the web app's (`mistorage-web`) only says it is up. See the Health group below.

Sample requests

The repository's mistorage-backend.http file carries ready-to-run requests for the Visual Studio / VS Code REST clients.

Response envelope

Every endpoint returns ApiResponse<T>: success, a human-readable message, the payload in data, and an optional errors list. Errors use the same shape with success: false. The one exception is GET /api/health, which answers in the health-check format.

ApiResponse<T>

{
  "success": true,
  "message": "Success",
  "data": { ... },
  "errors": null
}

Authentication

Access tokens are JWTs that expire after 15 minutes and are held in browser memory only. Each audience mints its own token with a userType claim (system, tenant or renter) and is validated by a matching policy; the tables below label each endpoint with the policy it requires.

Send the access token as Authorization: Bearer <token>.
A refresh token is set as an HTTP-only cookie on login and read back by the audience's refresh endpoint. Refresh tokens are hashed at rest and rotated on every use.
Each audience has its own refresh-token table (RefreshTokens, TenantRefreshTokens, RenterRefreshTokens), so a cookie from one can never be presented to another.
Renter identity is always read from the token's sub claim, never from a route or body parameter.

Cross-site cookies and the frontend relay

From the browser the API is cross-site, so a refresh cookie it sets is one the frontend's own middleware can never read. The frontend therefore relays auth calls server-side (/api/*-auth/* routes, POST only) and re-issues the cookie first-party. Bearer calls go direct — except POST api/tenant-auth/enter, which is relayed and carries HQ's bearer, so the relay forwards Authorization. The relay may forward the real client address in X-Client-Ip, which the API honours only when X-Proxy-Secret matches Security:TrustedProxySecret.

Renter session policy (RenterAuth section, all keys have defaults)
Key	Default	What it does
`RememberMeDays`	30	"Remember me" ticked: a persistent cookie with a rolling window that each rotation renews.
`RememberMeAbsoluteDays`	180	Ceiling on a remembered session, counted from sign-in, that no activity extends.
`SessionHours`	12	"Remember me" unticked: a session cookie, plus a server-side backstop that does not roll.
`RotationGraceSeconds`	30	How long a just-rotated token stays acceptable to the browser that rotated it — covers second-tab and reload-mid-flight races.
`MaxConcurrentSessions`	10	Live sessions per renter. At the ceiling the idlest is signed out, never the one signing in.
`RevokedRetentionDays`	2	How long a revoked row survives. While it exists a replay is recognised as theft; once swept it is merely unknown.

Rate limits

Per-IP budgets, grouped so one surface can never eat another's allowance. First matching rule wins.

Bucket	Paths	Budget
`auth`	`/api/auth/` and `/api/tenant-auth/` login, register, forgot / reset password	10 / min
`renter-auth`	`/api/renter-auth/*` login, register, verify, resend, forgot / reset password	10 / min
`rental`	`/api/rental/start`, `/api/rental/quote`	20 / min
`public`	`/api/public/*` — the anonymous storefront	120 / min
`security-reports`	`/api/security/*` — CSP and integrity reports	60 / min

Renter auth is deliberately separate from staff auth: renters arrive in far greater numbers, and a shared allowance would let them exhaust the budget staff need to sign in. Refresh, HQ's tenant-auth/enter (there is no password to guess) and /api/health (monitors poll it) are unmetered on purpose.

The SaaS feature flag

Endpoints marked SaaS only below belong to the archived multi-tenant model. With Saas:Enabled off (the default) they answer 404 Not found to everyone, signed in or not. Three others change shape rather than disappear: POST api/tenant-auth/register becomes an administrator action, rent settles to the configured merchant regardless of per-location boarding, and GET api/dashboard/stats returns operator figures (occupancy, rent roll, arrears) instead of SaaS ones (MRR, subscriptions, churn).

Endpoint reference

Grouped by audience. Paths are relative to the API base URL; {id}-style segments are GUIDs unless noted.

Public storefront

Anonymous, read-only, GET only. Only live locations and Available units are visible. Responses are cacheable for 60 seconds. {subdomain} resolves a location by subdomain first, custom domain second.

Endpoint	Auth	Notes
GET`api/public/{subdomain}`	Anonymous	Location profile plus the size guide, annotated with live availability. The one call a storefront landing page needs.
GET`api/public/{subdomain}/units`	Anonymous	A page of available units. Query: `category`, `climateControlled`, `sort` (rate, rate_desc, size, size_desc, name), `page`, `pageSize` (default 24, max 100).
GET`api/public/{subdomain}/units/{id}`	Anonymous	One unit, for the detail view and the checkout's confirm step.

Renter authentication

Identity for storage customers. Accounts are scoped to one location. With RenterAuth:RequireEmailVerification on, registration returns no session and login is refused until the address is confirmed; with it off, registration signs the renter straight in.

Endpoint	Auth	Notes
POST`api/renter-auth/register`	Anonymous	Create a renter account at a location.
POST`api/renter-auth/verify-email`	Anonymous	Confirm the address with the emailed token.
POST`api/renter-auth/resend-verification`	Anonymous	Send a fresh verification link.
POST`api/renter-auth/forgot-password`	Anonymous	Start password recovery. Uniform response regardless of whether the address exists.
POST`api/renter-auth/reset-password`	Anonymous	Finish password recovery with the emailed token.
POST`api/renter-auth/login`	Anonymous	Returns an access token and sets the refresh cookie. `rememberMe` selects the persistent policy.
POST`api/renter-auth/refresh`	Anonymous	Cookie-authenticated. Rotates the refresh token and returns a new access token.
POST`api/renter-auth/revoke`	Anonymous	Cookie-authenticated sign-out for this session only.
POST`api/renter-auth/revoke-all`	Renter token	Sign out every session for this renter.
GET`api/renter-auth/profile`	Renter token	The renter's own profile.
PUT`api/renter-auth/profile`	Renter token	Update the renter's own profile.
GET`api/renter-auth/me`	Renter token	Who am I, from the token.

Rental flow

The renter-facing half of renting a unit. Quotes are anonymous; anything touching money needs the Renter policy, and the location comes from the token.

Endpoint	Auth	Notes
GET`api/rental/quote/{subdomain}/{unitId}`	Anonymous	What this unit will cost before a card is entered. Optional `startDate` query. Includes which application fields the location asks for.
GET`api/rental/payment-config/{subdomain}`	Anonymous	What the browser needs to tokenize a card at this location.
POST`api/rental/start`	Renter token	Charge the card (when the gateway is enabled), create the lease, take the unit off the market. First invoice is left outstanding when the gateway is off.
GET`api/rental/my-leases`	Renter token	The signed-in renter's leases.
GET`api/rental/my-leases/{leaseId}`	Renter token	One lease in full — the account's unit page.
PUT`api/rental/my-leases/{leaseId}/move-out-notice`	Renter token	Give notice to move out. Not a cancellation: the lease stays active and rent keeps accruing until staff end it.
DELETE`api/rental/my-leases/{leaseId}/move-out-notice`	Renter token	Withdraw a notice that has not been acted on yet.
GET`api/rental/my-invoices`	Renter token	The signed-in renter's rent invoices.

Renter account

What a signed-in renter does with their own account. Every action reads the renter id from the token.

Endpoint	Auth	Notes
GET`api/renter-account/addresses`	Renter token	The address book.
POST`api/renter-account/addresses`	Renter token	Add an address.
PUT`api/renter-account/addresses/{addressId}`	Renter token	Edit an address.
PUT`api/renter-account/addresses/{addressId}/default`	Renter token	Make this the default address (demotes the previous one).
DELETE`api/renter-account/addresses/{addressId}`	Renter token	Remove an address.

Location staff authentication

Sign-in for a location's staff. Under the single-operator model there is no self-service registration: accounts are created by HQ or by an existing colleague.

Endpoint	Auth	Notes
POST`api/tenant-auth/register`	Staff token	Create a staff account. With SaaS off this requires a token: a colleague's (the location comes from the token) or HQ's (the location comes from the body's `subdomain`). Returns no session. Under SaaS it is anonymous self-service. HQ normally uses the Staff tab instead.
POST`api/tenant-auth/login`	Anonymous	Returns an access token and sets the refresh cookie.
POST`api/tenant-auth/enter`	HQ token	"Manage Facility" from HQ. Body `{ customerId }`; HQ's bearer token yields an ordinary staff session (and refresh cookie) as the location's Owner, without a second login. The location must be active; a location older than Owner seeding gets its Owner created on first entry. The Owner's other sessions are left alone. Audited as `Location.Entered`.
POST`api/tenant-auth/refresh`	Anonymous	Cookie-authenticated token rotation.
POST`api/tenant-auth/revoke`	Anonymous	Cookie-authenticated sign-out.
GET`api/tenant-auth/me`	Staff token	The signed-in staff member and their location.
POST`api/tenant-auth/forgot-password`	Anonymous	Start password recovery.
POST`api/tenant-auth/reset-password`	Anonymous	Finish password recovery.
GET`api/tenant-auth/check-subdomain`	Anonymous	Is this subdomain taken?
POST`api/tenant-auth/self-register`	AnonymousSaaS only	Company self-signup with a card.
GET`api/tenant-auth/payment-config`	AnonymousSaaS only	Platform merchant config for subscription checkout.
GET`api/tenant-auth/plan/{customerId}`	Staff tokenSaaS only	The company's current subscription plan.
POST`api/tenant-auth/plan/{customerId}/upgrade`	Staff tokenSaaS only	Change subscription plan.

Location console

Everything a location's staff do day to day. {customerId} is the location, and must match the one in the caller's token.

Endpoint	Auth	Notes
GET`api/tenant/{customerId}/dashboard`	Staff token	The location's dashboard figures.
GET`api/tenant/{customerId}/units`	Staff token	All units at the location.
GET`api/tenant/{customerId}/units/size-categories`	Staff token	The size guide: every category with label, blurb, icon and typical dimensions.
GET`api/tenant/{customerId}/units/{id}`	Staff token	One unit.
POST`api/tenant/{customerId}/units`	Staff token	Create a unit. Size category derives from the dimensions; status starts as Available. Names are unique within a location.
PUT`api/tenant/{customerId}/units/{id}`	Staff token	Edit a unit: name, rate, dimensions, climate control, out-of-service, and its own application-field overrides.
PATCH`api/tenant/{customerId}/units/{id}/assign`	Staff token	Assign a renter to a unit (staff-side rental).
PATCH`api/tenant/{customerId}/units/{id}/vacate`	Staff token	Return a unit to Available.
DELETE`api/tenant/{customerId}/units/{id}`	Staff token	Delete a unit.
GET`api/tenant/{customerId}/renters`	Staff token	Renters at this location. Carries no application data, so a page of renters never holds everyone's licence numbers.
GET`api/tenant/{customerId}/renters/{id}`	Staff token	One renter, with the rental application from checkout in `application`: cell phone, driver's licence, alternate and emergency contacts, employer, referral, texting consent, `hasAccount`, `isEmailVerified`. The SSN is never returned — only `hasSocialSecurityNumber`. `null` for a renter staff created.
POST`api/tenant/{customerId}/renters`	Staff token	Create a renter record on the renter's behalf.
PUT`api/tenant/{customerId}/renters/{id}`	Staff token	Edit a renter. Leaves the application fields untouched.
DELETE`api/tenant/{customerId}/renters/{id}`	Staff token	Delete a renter.
GET`api/tenant/{customerId}/leases`	Staff token	All leases at the location, optionally filtered by `status`.
POST`api/tenant/{customerId}/leases/{leaseId}/end`	Staff token	Move-out: ends the lease, returns the unit to Available, stops further rent, and only if explicitly asked writes off what is owed.
GET`api/tenant/{customerId}/settings`	Staff token	The location's own settings: the phone number renters see, and which application fields it asks for.
PUT`api/tenant/{customerId}/settings`	Staff token	Update those settings. Nothing that decides money, renames or re-subdomains the location.
GET`api/tenant/{customerId}/notifications/templates`	Staff token	Notification templates.
POST`api/tenant/{customerId}/notifications/templates`	Staff token	Create a template.
PUT`api/tenant/{customerId}/notifications/templates/{id}`	Staff token	Edit a template.
PATCH`api/tenant/{customerId}/notifications/templates/{id}/toggle`	Staff token	Enable / disable a template.
DELETE`api/tenant/{customerId}/notifications/templates/{id}`	Staff token	Delete a template.
POST`api/tenant/{customerId}/notifications/recipients`	Staff token	Resolve a recipient selection to renters.
POST`api/tenant/{customerId}/notifications/preview`	Staff token	Render a template against a recipient.
POST`api/tenant/{customerId}/notifications/send`	Staff token	Send a batch.
GET`api/tenant/{customerId}/notifications/history`	Staff token	Sent notifications.
GET`api/tenant/{customerId}/notifications/{id}`	Staff token	One notification.
GET`api/tenant/{customerId}/notifications/unread-count`	Staff token	Badge count.

HQ authentication

Sign-in for system users behind /super-admin.

Endpoint	Auth	Notes
POST`api/auth/register`	Anonymous	Create a system user. Open registration here is a known gap under the single-operator model and is tracked in the configuration checklist.
POST`api/auth/login`	Anonymous	Returns an access token and sets the refresh cookie.
POST`api/auth/refresh`	Anonymous	Cookie-authenticated token rotation.
POST`api/auth/revoke`	Anonymous	Cookie-authenticated sign-out.
GET`api/auth/me`	HQ token	The signed-in user with role and permissions.
POST`api/auth/forgot-password`	Anonymous	Start password recovery.
POST`api/auth/reset-password`	Anonymous	Finish password recovery.

HQ — locations and their staff

The Customer entity, which under the single-operator model means a location. The staff endpoints sit behind the location page's Staff tab, live since 2026-09-22. None of them sends email.

Endpoint	Auth	Notes
GET`api/customer`	HQ token	List locations. Query: `search`, `status`, `page`, `pageSize`, `sortBy`, `sortOrder`.
GET`api/customer/{id}`	HQ token	One location.
POST`api/customer`	HQ token	Create a location and seed its Owner login. One contact email may name several locations (unique only under SaaS); subdomains stay unique.
PUT`api/customer/{id}`	HQ token	Edit a location.
PATCH`api/customer/{id}/status`	HQ token	Change status. Body: `{ status, reason }`.
POST`api/customer/{id}/ban`	HQ token	Ban a location. Body: `{ reason, banUntil }`.
POST`api/customer/{id}/unban`	HQ token	Lift a ban.
DELETE`api/customer/{id}`	HQ token	Delete a location.
GET`api/customer/{id}/staff`	HQ token	The location's logins, Owner first: `{ id, firstName, lastName, email, role, isActive, createdAt, lastSeenAt }`. `lastSeenAt` is the latest session issued, not the latest password login.
POST`api/customer/{id}/staff`	HQ token	Add a login. Body: `{ firstName, lastName, email, password, confirmPassword, role? }`. `role` is `Manager` (default) or `Staff` — never Owner. Password 8–128 characters with an uppercase letter and a digit; email unique within the location. Audited.
PATCH`api/customer/{id}/staff/{staffId}/active`	HQ token	Activate / deactivate a login. Body: `{ isActive }`. Deactivating ends all its sessions; the Owner cannot be deactivated. Audited.
PUT`api/customer/{id}/staff/{staffId}/password`	HQ token	Set a new password. Body: `{ newPassword, confirmPassword }`. Signs that login out everywhere. Audited, without the password.

HQ — users, roles and permissions

System users and the RBAC behind them.

Endpoint	Auth	Notes
GET`api/user`	HQ token	List system users.
GET`api/user/{id}`	HQ token	One user.
POST`api/user`	HQ token	Create a user.
PUT`api/user/{id}`	HQ token	Edit a user.
PATCH`api/user/{id}/toggle-active`	HQ token	Activate / deactivate.
DELETE`api/user/{id}`	HQ token	Delete a user.
GET`api/user/roles`	HQ token	Roles (Super Admin / Admin / Manager) and their permissions.
GET`api/user/permissions`	HQ token	All permissions.
PUT`api/user/roles/{roleId}/permissions`	HQ token	Replace a role's permission set.

HQ — dashboard, protection plans, tasks, settings

The rest of the owner-level console.

Endpoint	Auth	Notes
GET`api/dashboard/stats`	HQ token	Operator figures: occupancy, rent roll, arrears. (Under SaaS: MRR, subscriptions, churn.)
GET`api/protectionPlans`	HQ token	Renter protection plans.
GET`api/protectionPlans/{id}`	HQ token	One plan.
POST`api/protectionPlans`	HQ token	Create a plan.
PUT`api/protectionPlans/{id}`	HQ token	Edit a plan.
PATCH`api/protectionPlans/{id}/toggle`	HQ token	Enable / disable.
DELETE`api/protectionPlans/{id}`	HQ token	Delete a plan.
GET`api/task`	HQ token	The HQ task board.
GET`api/task/{id}`	HQ token	One task.
POST`api/task`	HQ token	Create a task.
PUT`api/task/{id}`	HQ token	Edit a task.
PATCH`api/task/{id}/move`	HQ token	Move a task between columns.
DELETE`api/task/{id}`	HQ token	Delete a task.
GET`api/settings`	HQ token	System settings, including the installation-wide application-field defaults.
PUT`api/settings`	HQ token	Update system settings.

HQ — notifications

Templates, batches, history and replies at owner level.

Endpoint	Auth	Notes
GET`api/notifications/templates`	HQ token	Templates.
POST`api/notifications/templates`	HQ token	Create a template.
PUT`api/notifications/templates/{id}`	HQ token	Edit a template.
PATCH`api/notifications/templates/{id}/toggle`	HQ token	Enable / disable a template.
DELETE`api/notifications/templates/{id}`	HQ token	Delete a template.
GET`api/notifications/companies`	HQ token	Locations available as recipients.
POST`api/notifications/recipients`	HQ token	Resolve a recipient selection.
POST`api/notifications/preview`	HQ token	Render a template.
POST`api/notifications/send`	HQ token	Send a batch.
GET`api/notifications/history`	HQ token	Sent notifications.
GET`api/notifications/{id}`	HQ token	One notification with its thread.
POST`api/notifications/{id}/reply`	HQ token	Reply on a thread.
GET`api/notifications/unread-count`	HQ token	Badge count.
PATCH`api/notifications/{id}/read`	HQ token	Mark as read.

HQ — payment gateway operations

Infrequent PhoenixGate admin operations, not a runtime pipeline. Readiness stays available under the single-operator model; boarding does not, because rent settles to the client's own merchant and there is nobody left to board.

Endpoint	Auth	Notes
GET`api/payment-admin/processing-profiles`	HQ token	Readiness: confirm the merchant reads transaction-ready on the gateway.
POST`api/payment-admin/custom-fields/invoice-number`	HQ token	Create the `InvoiceNumber` custom field on the merchant so every charge carries the invoice number. Safe to repeat.
POST`api/payment-admin/board`	HQ tokenSaaS only	One-time reseller boarding of a location's own merchant.
GET`api/payment/subscription/{subscriptionId}/autopay`	HQ token	Autopay enrolment state for a subscription.
POST`api/payment/subscription/{subscriptionId}/autopay`	HQ token	Enrol / change autopay.
POST`api/payment/reconcile`	HQ token	Poll-based reconciliation against the gateway.

Archived — SaaS billing

Subscription plans, platform invoices and operator cards on file. All of these answer 404 while Saas:Enabled is false. Listed so the flag's effect is visible.

Endpoint	Auth	Notes
GET`api/subscriptionplan`	AnonymousSaaS only	Public plan list.
GET`api/subscriptionplan/{id}`	HQ tokenSaaS only	One plan.
POST`api/subscriptionplan`	HQ tokenSaaS only	Create a plan.
PUT`api/subscriptionplan/{id}`	HQ tokenSaaS only	Edit a plan.
PATCH`api/subscriptionplan/{id}/toggle`	HQ tokenSaaS only	Enable / disable.
DELETE`api/subscriptionplan/{id}`	HQ tokenSaaS only	Delete a plan.
GET`api/invoice`	HQ tokenSaaS only	Platform invoices.
GET`api/invoice/summary`	HQ tokenSaaS only	Billing summary (SQL-side aggregation).
GET`api/invoice/customer/{customerId}`	HQ tokenSaaS only	Invoices for one company.
GET`api/invoice/{id}`	HQ tokenSaaS only	One invoice.
POST`api/invoice`	HQ tokenSaaS only	Create an invoice.
PUT`api/invoice/{id}`	HQ tokenSaaS only	Edit an invoice.
POST`api/invoice/{id}/payment`	HQ tokenSaaS only	Record a payment.
PATCH`api/invoice/{id}/mark-overdue`	HQ tokenSaaS only	Mark overdue.
PATCH`api/invoice/{id}/cancel`	HQ tokenSaaS only	Cancel.
POST`api/invoice/generate`	HQ tokenSaaS only	Generate the period's invoices.
POST`api/invoice/{id}/charge`	HQ tokenSaaS only	Charge the card on file.
POST`api/invoice/{id}/refund`	HQ tokenSaaS only	Refund.
GET`api/payment-method/customer/{customerId}`	HQ tokenSaaS only	A company's cards on file.
POST`api/payment-method/customer/{customerId}`	HQ tokenSaaS only	Add a tokenized card.
PATCH`api/payment-method/customer/{customerId}/{paymentMethodId}/default`	HQ tokenSaaS only	Make default.
DELETE`api/payment-method/customer/{customerId}/{paymentMethodId}`	HQ tokenSaaS only	Remove a card.

Health

For uptime monitors. Anonymous, unthrottled, never cached, and outside the response envelope.

Endpoint	Auth	Notes
GET`api/health`	Anonymous	`{ "status", "service": "mistorage-api", "checks": { "database" } }`: 200 when Postgres answers, 503 when it does not. Check names and statuses only — no exception text. Nothing else (email, payment gateway) is checked.
GET`/api/health · web app`	Anonymous	On the frontend's own origin: `{ "status": "Healthy", "service": "mistorage-web" }` with `Cache-Control: no-store`. Says the web app is up; it does not call the API.

Security reporting

Collection point for browser-side integrity signals on the payment pages. Anonymous by necessity; contents are a lead, never evidence. Bodies are size-capped and every field truncated before logging.

Endpoint	Auth	Notes
POST`api/security/csp-report`	Anonymous	CSP violation reports — accepts the legacy `csp-report` envelope and the Reporting API array.
POST`api/security/page-integrity`	Anonymous	Page-integrity findings from the payment pages. Logged at Error.