API field permissions: avoid mass assignment and overly broad responses

Two directions of the same boundary

Mass assignment occurs when convenient automatic binding transfers more input fields to internal properties than the caller may change. The defect may emerge only when the model grows later: a new internal field suddenly also enters the public update path.

The reverse direction is overly broad data output. An application might return an internal review note even though the frontend displays only public status. Hiding it in the browser does not protect content already transmitted. OWASP groups both directions under API3:2023, Broken Object Property Level Authorization. OWASP API3:2023.

Access to the object itself must first be permitted; see BOLA and IDOR. Field permissions then determine which portion the caller may edit or see. A valid JSON schema and the presence of a role key do not decide this permission.

Separate input, internal state and output

A data transfer model, often called a DTO, describes the deliberately exposed subset for an operation. It need not share the database model's properties. Reading and writing may also require different models.

This table applies to the fictional application, not every product. It illustrates the design question: an internal value can be necessary while appearing in no public profile model. OWASP recommends explicitly permitted bindings and separate DTOs instead of mapping external input directly to domain objects. OWASP Mass Assignment.

Explicit field selection remains stable as models grow

The following local Python example demonstrates field selection only. Prerequisites: the request has already been parsed as an object, values have been appropriately validated, and the caller may edit the affected profile. Without those prior decisions, the function would not be a secure endpoint.

EDITABLE_FIELDS = {"display_name", "time_zone"}

def select_profile_changes(payload):
    if set(payload) - EDITABLE_FIELDS:
        raise ValueError("Forbidden fields")
    return {
        name: payload[name]
        for name in EDITABLE_FIELDS
        if name in payload
    }

def public_profile(record):
    return {
        name: record[name]
        for name in ("id", "display_name")
    }

A review_note added to the internal object later therefore does not automatically appear in output. An additional role is rejected in the update request instead of being copied into the record. Both functions have been checked locally with synthetic data. Role-dependent models, nested objects, database access and HTTP behaviour are not included.

If different roles may change different fields, derive the permitted model from the server-side policy and concrete action. A client parameter such as mode=admin must not authorise that selection itself. Even a comprehensive ‘admin model’ should not expose unnecessary secrets.

A schema helps only when appropriately enforced

A request schema can reject unexpected properties. In a simple JSON Schema object, additionalProperties: false excludes properties not covered by properties or patternProperties. The restriction must appear at the relevant object level and interact correctly with the schema compositions used. JSON Schema Core 2020-12, section 10.3.2.

Text in an OpenAPI file does not itself cause runtime validation. Even a correctly enforced schema may allow the wrong fields: if role explicitly appears in the normal profile model, prohibiting additional fields does not prevent this. Schema, field policy and actual mapping must describe the same intended behaviour.

Annotations such as readOnly or writeOnly are not automatic authorisation mechanisms either. Your tooling must actually implement their meaning; this caller's permission remains an application decision. The validation guide explains structural, value and runtime checks.

Partial updates and nested data need their own rules

In partial updates, ‘field missing’ and ‘field is null’ often differ: the former may mean ‘leave unchanged’, the latter ‘delete the value’. Document and test this meaning. A silent default must not turn an omitted property into an unintended change.

Nested objects are no exception. Permission to edit a contact address does not grant permission to change an organisation assignment hidden inside it. Permitted fields must therefore recursively match your concrete input contract. In lists of changes, every affected object additionally requires object authorisation.

Do not expose internal state transitions as freely editable fields. An ‘approve report’ action can check role, state and other conditions; freely setting approved: true often represents that decision inadequately. Securing business logic explores these flows.

Check stored fields and data actually transmitted

Use an isolated environment with synthetic profiles. An allowed field must be editable; a forbidden field must not change the internal value. Inspect the stored record and derived events, not just the response body. Some internal fields are deliberately invisible in responses.

For output, compare fields transmitted across roles and paths. A list, detail retrieval, export and GraphQL selection may use different serialisers. Add a new internal field to the test model and check that it is neither returned nor accepted without an explicit contract change. This tests the intended boundary against later model extensions.

Introduce stricter field contracts without an uncontrolled fallback

Before migration, identify additional fields that legitimate clients currently send. Explicitly decide whether these will be rejected or ignored for compatibility. Either can make business sense; in neither case may forbidden values be accepted. Error guidance should help the client correct the request without listing internal field names or data holdings.

If the stricter version blocks a required client, extend the permitted contract deliberately or return to a previously verified narrow projection. A general object copy as rollback would reopen the boundary. The public API Security Check does not verify these input and output permissions.

Next, roles and permissions and testing your own API security connect field selection with the whole call. For public header or method signals, reading HTTP findings leads to suitable, bounded evidence.

Next steps