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

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.

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. 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 is 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 an owner or colleague's token, takes the location from the token, and returns no session. Under SaaS it is anonymous self-service.
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: an administrator's bearer token yields a staff session as the location's Owner, without a second login. Audited.
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.
GET`api/tenant/{customerId}/renters/{id}`	Staff token	One renter.
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.
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 were added 2026-09-17 behind the location page's Staff tab.

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. One contact email may name several locations.
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 staff logins.
POST`api/customer/{id}/staff`	HQ token	Add a staff login. Body: `{ firstName, lastName, email, password, confirmPassword, role? }`.
PATCH`api/customer/{id}/staff/{staffId}/active`	HQ token	Activate / deactivate a login. Body: `{ isActive }`.
PUT`api/customer/{id}/staff/{staffId}/password`	HQ token	Set a new password. Body: `{ newPassword, confirmPassword }`.

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.

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.