API contract
This screen is the public explanation of the EZ Move API. Every server function is guarded twice: a wrong role is refused, and bad input is refused. The refusal body names the rule that refused, and when a field is wrong it names that field. Database error messages are never returned. Fake data only.
How a request is decided
- The session is checked. No session, a forged session, or an expired session is
401 sign_in_required. - The role matrix is the first check. If this role may not perform that operation on that entity, the API returns
403withrule: "role_matrix", plus the entity and the operation. - Bad input is refused before the database writes. A missing required field returns
400withrule: "required"andfield. An unknown column returnsrule: "writable_columns"andfield. A value outside the written check (enum, range, positive integer, max length) returns that rule and the field. A non-integer id returnsrule: "bad_id". - Row policy is the second check. If the row is not this session’s to see or change, the API returns
403withrule: "row_policy"(a row in another tenant looks like a row that does not exist onGET). - A remaining database constraint is mapped to
422withrule: "constraint". The database message is not returned.
Refusal shape
{
"error": "missing",
"rule": "required",
"field": "name",
"entity": "clients"
}
The published contract at /api/openapi.json (and /api/v1/openapi.json) documents the Refusal schema, including every rule name: role_matrix, writable_columns, row_policy, constraint, required, enum, range, positive_int, maxlen, bad_id.
Covered server functions
Contract tests walk the full set derived from the role matrix: every entity × role × operation (list, get, create, update, delete), every stats path, and the audit and metrics paths, plus a missing-field, unknown-column, bad-value, and bad-id probe on every write path that exists. They run on every change (npm test and the prebuild hook).
Live contract check
Enter as a demo persona on the plan-a-move screen, then return here. This page will read /api/openapi.json with that session and confirm the Refusal schema is published. It does not send real personal data; personas are fake.
Checking for a demo session…