Alignment audit — Screens → API → ERD → Schema → FE

One thin fetch wrapper. Cookies carry auth (credentials: "include"); X-Requested-With: XMLHttpRequest on state-changing requests is the CSRF defence pair. ApiError exposes isUnauthorized / isForbidden / isUnprocessable predicates so screens key UI off the status.

await api.createPropertyReport({ address_query: "M14 5JT" });
// → fetch("/api/v1/property_reports", {
//     method: "POST",
//     credentials: "include",
//     headers: { "X-Requested-With": "XMLHttpRequest", ... },
//     body: '{"property_report":{"address_query":"M14 5JT"}}' })

The whole API is namespaced under /api/v1 with format: :json. Today: me + me/active_role_grant + me/active_tenancy_membership + property_reports (index / show / create). Every other path in the OpenAPI surface is contract-only (no route here yet — see G3).

namespace :api, defaults: { format: :json } do
  namespace :v1 do
    resource :me, only: :show, controller: "me" do
      post :active_role_grant, to: "me#set_active_role_grant"
      post :active_tenancy_membership, to: "active_tenancy_memberships#create"
    end
    resources :property_reports, only: [:index, :show, :create]
  end
end

Auth/authz isn't scattered before_action hooks any more — every controller declares an ordered guard chain via the guard macro (#353). Api::BaseController sets the canonical chain; PropertyReportsController opts in to the tenancy-membership guard for index/show but not for the pre-tenancy create.

# packs/core/app/controllers/api/base_controller.rb
class Api::BaseController < ApplicationController
  skip_forgery_protection
  include Api::Pipeline

  guard Api::Guards::Authenticated
  guard Api::Guards::CsrfDefence,     only: :state_changing
  guard Api::Guards::AccountState,    only: :state_changing
  guard Api::Guards::ActiveRoleGrant
  guard Api::Guards::Authorize
  guard Api::Guards::Entitlement,     only: :state_changing
end

# packs/property_due_diligence/.../property_reports_controller.rb
class Api::V1::PropertyReportsController < Api::BaseController
  guard Api::Guards::ActiveTenancyMembership, except: :create
  ...
end

The mixin installs one before_action :run_api_pipeline per controller. The engine resolves the per-action guard list (honouring only / except / if / replaces), runs guards in declared order, and short-circuits on the first deny. The resolved Principal the guards populate is exposed to Pundit via @pundit_user.

def run_api_pipeline
  context = Context.new(controller: self)
  @pundit_user = context.principal  # bound for ApplicationController#pundit_user

  self.class.resolved_pipeline_for(self).each do |declaration|
    result = declaration.guard_class.new.call(context)
    return render_pipeline_failure(declaration.guard_class, result) if result.deny?
  end
end

Guards are stateless and uniform. They never render / raise / redirect themselves — they return a Result and let the failure renderer translate denies into JSON.

# packs/core/app/lib/api/guards/authenticated.rb
module Api::Guards
  class Authenticated < Base
    def call(context)
      return Result.allow if context.principal.authenticated?

      Result.deny(reason: :unauthenticated, http_status: 401)
    end
  end
end

The pipeline has run; the controller method is plain Rails. authorize consults PropertyReportPolicy (which delegates to Tenancy::PolicyHelpers for owner / active-membership / withdrawn-ledger reach). report.save fires Audited callbacks. Anything that could time out (per-source aggregator calls) runs off the request path via SolidQueue.

def create
  report = PropertyReport.new(create_params.merge(account: current_account, status: :pending))
  authorize report          # Pundit; raises NotAuthorizedError on deny

  if report.save             # Audited writes the create audit in the same txn
    PropertyReportAggregationJob.perform_later(report.id)
    render json: PropertyReportSerializer.new(report).serialize, status: :accepted
  else
    render json: { errors: report.errors }, status: :unprocessable_content
  end
end

Alba shapes the response. Timestamps are explicitly iso8601-formatted so the rswag schema check stays green. The FE-side type for PropertyReport comes from generated.ts, regenerated from swagger.yaml and CI-gated against drift.

# 202 Accepted
{
  "id": 42,
  "address_query": "M14 5JT",
  "status": "pending",
  "payload": {},
  "created_at": "2026-05-11T10:00:00Z",
  "tenancy_id": null
}