Access Rights

Overview

The @Access decorator controls how fields are read and written through the API. Each field can be set to read-only, write-only, or read-write, providing fine-grained control over data exposure. Access modes can also be overridden on a per-action basis, allowing different permissions for get, list, new, and edit operations.

Access Modes

The AccessMode enum defines three permission levels:

import { Access, AccessMode } from "@antelopejs/interface-data-api/metadata";

Basic Usage

Read-Only Fields

Read-only fields appear in API responses but cannot be modified through create or update requests. Values sent for these fields in request bodies are silently ignored.

@RegisterDataController()
class UserAPI extends DataController(
  User,
  DefaultRoutes.All,
  Controller("/users"),
) {
  @ModelReference()
  @Model(UserModel, "my-database")
  declare userModel: UserModel;

  @Access(AccessMode.ReadOnly)
  declare _id: string;

  @Access(AccessMode.ReadOnly)
  declare createdAt: string;

  @Access(AccessMode.ReadWrite)
  declare name: string;
}

A PUT request to /users/edit?id=user-123 with { "createdAt": "2025-01-01", "name": "Alice" } updates only name. The createdAt field is ignored.

Write-Only Fields

Write-only fields accept input during create and update operations but are never included in API responses. This is useful for sensitive data like passwords.

@RegisterDataController()
class UserAPI extends DataController(
  User,
  DefaultRoutes.All,
  Controller("/users"),
) {
  @ModelReference()
  @Model(UserModel, "my-database")
  declare userModel: UserModel;

  @Access(AccessMode.ReadWrite)
  declare name: string;

  @Access(AccessMode.ReadWrite)
  declare email: string;

  @Access(AccessMode.WriteOnly)
  declare password: string;
}

A GET request to /users/get?id=user-123 returns name and email but never includes password:

{
  "name": "Bob",
  "email": "[email protected]"
}

Read-Write Fields

Read-write fields are fully accessible: they appear in responses and accept input in request bodies.

@Access(AccessMode.ReadWrite)
declare email: string;

@Access(AccessMode.ReadWrite)
declare name: string;

Per-Action Overrides

The @Access decorator accepts an optional second argument to override the access mode for specific actions. This allows a field to behave differently depending on the operation being performed.

@Access(defaultMode: AccessMode, overrides?: Record<string, AccessMode>)

The overrides object maps action names ("get", "list", "new", "edit") to an AccessMode value. Actions not listed in the overrides use the default mode.

Example: Writable on Create, Read-Only on Edit

@RegisterDataController()
class UserAPI extends DataController(
  User,
  DefaultRoutes.All,
  Controller("/users"),
) {
  @ModelReference()
  @Model(UserModel, "my-database")
  declare userModel: UserModel;

  @Access(AccessMode.ReadOnly)
  declare _id: string;

  @Access(AccessMode.ReadWrite)
  declare name: string;

  // role can be set when creating, but cannot be changed during edit
  @Access(AccessMode.ReadWrite, { edit: AccessMode.ReadOnly })
  declare role: string;

  // age is read-only by default, but writable during creation
  @Access(AccessMode.ReadOnly, { new: AccessMode.ReadWrite })
  declare age: number;
}

In this configuration:

• role is readable and writable in all operations except edit, where it becomes read-only.
• age is read-only by default but can be set during new (create) operations.

Fields Without @Access

Fields declared without the @Access decorator are not exposed through the API at all. They do not appear in responses and are not accepted in request bodies. To include a field in the API, you must explicitly set its access mode.

Next Steps

See the validators documentation to learn how to enforce validation rules on field values.