Access rules

Every entity served by the Data API can carry an access: block that governs which services may call it, which operations a principal may run, which rows those operations touch, and which columns come back. All four tiers use one rule shape and one binding vocabulary, so a rule reads the same wherever it appears.

The four tiers

entities:
  - name: invoice
    access:
      services: [billing.svc]                                              # Tier 0 — which SERVICES may call at all
      actions:                                                             # Tier 1 — may this principal do this OPERATION?
        read:   { language: expr, expression: "true" }
        create: { language: expr, expression: '"admin" in user.roles' }
      rls:                                                                 # Tier 2 — which ROWS may they see / touch?
        read:   { language: expr, expression: "row.tenant_id == user.tenant_id" }
      fields:                                                              # Tier 3 — which COLUMNS may they project?
        read:   { language: expr, expression: 'field != "ssn" || "pii-reader" in user.roles' }

Tier	Key	Question	Enforced by
0	services:	Is the calling service on the allow-list?	Query compiler
1	actions:	May this principal run this operation?	Runtime hook + query compiler
2	rls:	Which rows does the operation apply to?	Query compiler (WHERE injection); in-process on create
3	fields:	May this principal project this column?	Query compiler (projection check)

A tier you omit is not applied — except that a missing Tier-1 rule is a denial for external callers. See Deny-by-default.

Deny-by-default

The Data API denies any operation on an entity that no Tier-1 rule governs, when the request is external. Three shapes count as “no rule”: no access: block at all, an access: block with no actions: map, and an actions: map with no key for this operation.

# No access block → every external GET / POST / PUT / DELETE returns 403.
- name: currency
  fields: [ ... ]

# Read is opted in. create / update / delete remain denied — they have no rule.
- name: currency
  access:
    actions:
      read: { language: expr, expression: "true" }
  fields: [ ... ]

The denial message is access denied (tier 1): entity "<name>" has no access rule for <op> (deny-by-default); declare an access.actions rule to permit it.

When the hook fires, and when it is bypassed

A request is external when the HTTP auth layer stamped an auth level on it. Both the authenticated middleware and the anonymous middleware do that — the anonymous one stamps anonymous even when the caller sends no header at all, so /anon/rest/* traffic is fully gated.

Caller	Gated by deny-by-default
Authenticated HTTP request (/rest/*, /graphql)	Yes
Anonymous HTTP request (/anon/rest/*, /anon/graphql)	Yes — principal has an empty user id and no roles
CLI seeding, bootstrap, migrations	No — no auth level on the context
Background and refresh runners	No
In-process calls from the hosting service	No
Engine-managed system entities (migration ledger, locks, plans)	No — exempt even for external callers

Where the safety net does not apply

Deny-by-default is a property of the runtime hook chain only. Four paths do not get it:

• The query compiler’s own access gate allows the unguarded. It denies only when a rule exists and evaluates false. Deny-by-default comes solely from the runtime hook.
• Named actions. On the composed-action path an entity with no access: block counts as allow for that entity; the base gate is the intersection of the referenced entities’ rules.
• System entities. Anything the engine manages itself is exempt at every tier.
• Internal callers. Nothing arriving without an auth level is checked, at any tier.

Tiers 2 and 3 have no equivalent hammer: an entity with actions: but no rls: returns every row.

The rule shape

Every rule — an action guard, an RLS predicate, a field rule — is a script reference with exactly these five keys:

Key	Meaning
language:	Which engine evaluates the body. Defaults to expr when empty.
expression:	An inline expression. The normal case.
script:	An inline script (a full program body). Same destination as expression:; if both are set, expression: wins.
script-file:	External script file URI. Does not execute — see below.
function:	Entry function name for a module script. Consumed only on the file path, so it does not execute either.

Accepted language: values: expr (the default), cel, js, javascript, lua, starlark, go, wasm. Anything else fails the rule at evaluation time. ts / typescript is not accepted.

read: { language: expr, expression: '"admin" in user.roles' }

Two of the five keys do not run

A rule whose body is script-file: (with or without function:) fails at evaluation with file-referenced scripts not yet wired. For an action guard that surfaces as access guard eval (<op>): … and an HTTP 500, not a denial. Only expression: and script: bodies execute today.

A non-empty string is ALLOW

Rule results are coerced to bool: only nil, false, 0, and "" deny. Any non-empty string is treated as allow — a rule that accidentally returns a message, an id, or a SQL fragment silently passes. A non-string, non-bool result (a list, a map, an object) is an evaluation error, which becomes a 500. Write rules that return a bool.

The binding vocabulary

One function builds the bindings for every rule, so the variable set is identical across tiers and engines.

Binding	Is
user.id	The caller’s user id
user.user_id	Alias of user.id
user.tenant_id	The caller’s tenant key
user.tenant	Alias of user.tenant_id
user.roles	The caller’s roles (a list)
user.service	The calling service identity
user.session_id	The session id
tenant	Top-level alias of user.tenant_id
entity	The entity name (not the row)
action	The operation: create / read / update / delete
operation	Alias of action
user_id, roles	Flat back-compat aliases; prefer the nested form
row.<column>	The row under evaluation
payload	The mutation body (runtime hook only, on writes)
field	The column name — field rules only, one evaluation per projected column
extended_action	purge / restore / unmask / decrypt — extended-action guards only
entities, params	Named-action guards only

Nothing else resolves.

user.tenant_id is the full tenant key

The binding carries the composed customer:product:env:tenant key (for example c1:iam:dev:t1), not a slug. tenant == "acme" never matches, and row.tenant_id == user.tenant_id only works if the column stores the same composed form.

entity is the entity name; row.* is the row data. Reach for row.status, never entity.status.

Rule bodies run without the request context: they cannot be cancelled by a request timeout and cannot read anything from the request.

Tier 0 — services

services: is an allow-list of calling service identities. Empty or absent means no service restriction.

access:
  services: [billing.svc, admin.svc]

The compile-time gate denies when the list is non-empty and the caller’s service identity is not on it. An empty service identity matches nothing, so it is refused rather than waved through.

services: denies every HTTP request on data.svc

Nothing on the HTTP path sets a calling-service identity: the principal built from the request carries a user id, a tenant key and roles, and no service. The runtime hook is therefore inert (it skips Tier 0 when its service identity is empty), and the compile-time gate sees an empty identity, matches it against your list, and refuses — every read and every write on that entity fails with a 500.

Declaring services: on an entity you serve over REST or GraphQL takes it off the air. Gate by principal with a Tier-1 rule instead.

Tier 1 — action guards

Slot	Evaluated on
create	Create
read	Read, list, search
update	Update, patch
delete	Delete
purge	Delete and ?purge — stacked on top of delete
restore	A restore mutation — stacked on top of update
unmask	Read and ?unmask — stacked on top of read
decrypt	Read and ?untokenize — stacked on top of read

The four extended guards are AND-stacked: they are evaluated in addition to the base CRUD guard, never instead of it. A caller who passes read but fails unmask is denied when they ask for unmasking. An extended flag outside its operation is ignored — ?purge on a read evaluates nothing.

This is the access block from the shipped end-to-end product schema, the one the PostgreSQL-backed access suite runs against:

entities:
  - name: customer
    description: "Customer master data"
    fields:
      - name: code
        type: string
        modifiers: [required, unique]
      - name: name
        type: string
        modifiers: [required]
      - name: tenant_id
        type: string
        nullable: true
      - name: owner_id
        type: string
        nullable: true
    access:
      actions:
        read:   { language: expr, expression: "true" }
        create: { language: expr, expression: "true" }
        update: { language: expr, expression: "true" }
        # Only an admin may delete. An anonymous caller carries no roles,
        # so this denies.
        delete: { language: expr, expression: '"admin" in user.roles' }

An anonymous DELETE /anon/rest/customer/id/<id> against that entity returns 403 with access denied and tier 1 in the body, and the row survives.

Action guards are identity decisions — use user.*, user.roles, tenant. For which rows a principal may touch, use RLS.

The all-slots shorthand

actions: also accepts a rule: (plus optional language:) that applies one body to all eight slots at once. A per-action key overrides it for that slot.

access:
  actions:
    language: expr
    rule: '"staff" in user.roles'                          # applies to all eight slots
    delete: { language: expr, expression: '"admin" in user.roles' }   # overrides for delete

Guards run twice

Each Tier-1 guard is evaluated once in the runtime hook and once when the query is compiled. A rule body with side effects runs twice per request, and the two evaluations build their bindings from different sources.

Tier 2 — RLS

Row-level security restricts which rows an operation applies to. Write it as a boolean predicate over row.* and user.*.

access:
  rls:
    read:   { language: expr, expression: "row.tenant_id == user.tenant_id" }
    update: { language: expr, expression: "row.tenant_id == user.tenant_id" }
    delete: { language: expr, expression: "row.tenant_id == user.tenant_id" }
    create: { language: expr, expression: "row.tenant_id == user.tenant_id" }

The nested rules: map form parses too, and the two merge with the top-level keys winning:

access:
  rls:
    rules:
      read: { language: expr, expression: "row.owner_id == user.id" }

The four top-level shortcut keys are create, read, update, and delete. The nested rules: map takes any key, and the compiler looks up whichever key names the operation it is compiling — including purge, restore, and upsert.

How each operation is enforced

Operation	Mechanism
read / update / delete	The predicate is compiled into the SQL WHERE — the database filters, and non-matching rows are never read or touched
create	An INSERT has no WHERE, so the new row is checked in-process against the rule; failure returns 403 access denied (tier 2): row denied by RLS create rule on entity <name>
purge / restore / upsert	Looked up under their own key — see the caution below

Values from a rule are parameterised, so no rule value can be injected as SQL. Column names come from the rule text and are emitted as quoted identifiers.

purge, restore and upsert do not fall back to a CRUD rule

The compiler names the operation before it looks the rule up, and a purge is named purge, not delete. An entity whose rls: block declares only delete gets no row predicate at all on DELETE …?purge=true — the rows the rule was meant to protect are hard-deleted. The same holds for a restore against an update-only block and an upsert against a create/update-only block.

Declare the extra keys explicitly under rules: when the entity supports those operations:

access:
  rls:
    rules:
      read:    { language: expr, expression: "row.tenant_id == user.tenant_id" }
      update:  { language: expr, expression: "row.tenant_id == user.tenant_id" }
      delete:  { language: expr, expression: "row.tenant_id == user.tenant_id" }
      purge:   { language: expr, expression: "row.tenant_id == user.tenant_id" }
      restore: { language: expr, expression: "row.tenant_id == user.tenant_id" }

Tier-1 guards are unaffected — purge and restore have their own actions: slots and are AND-stacked on the base operation.

The user side folds

user.* and tenant are known when the query is compiled, so any subtree that references no row.* is evaluated against the principal and folded to a constant. That makes the role-bypass pattern work exactly as written:

rls:
  read: { language: expr, expression: '"admin" in user.roles || row.owner_id == user.id' }

• An admin — the left branch folds to true, so the whole rule folds to true, so no predicate is added and every row is visible.
• A non-admin — the left branch folds to false and drops, leaving owner_id = <their id>.

A rule that folds to false produces the deny-all predicate id = NULL, which is never true for a persisted row.

The grammar the translator accepts

Category	Accepted
Logical	&&, and, ||, or, !, not
Comparison	==, !=, <, >, <=, >= — one side must be row.<column>; sides may be in either order
Column to column	row.a == row.b — compiled as a real column reference, not a parameter
Membership	row.<column> in [ … ] where the right side resolves to a list; "<const>" in user.roles is folded
Literals	string, integer, float, bool, nil, array
Foldable identifiers	tenant, true, false, and user. + id / user_id / userid / tenant / tenant_id / tenantid / service / session_id / sessionid / session / roles

Anything outside this set is untranslatable: an unsupported operator, a bare row.x used as a term, an in whose right side is a row.*, an unknown identifier, or a user.<field> outside the foldable set.

An untranslatable RLS rule silently returns zero rows

data.svc compiles RLS in strict mode: a rule the translator cannot compile becomes the deny-all predicate. The caller gets 200 with an empty result set — no error, no log line, and no boot-time validation of RLS rules. A rule with a typo is indistinguishable from an empty table.

The most common cause is legacy template syntax: {{user.id}} == row.owner_id no longer parses. Rewrite it as user.id == row.owner_id.

Strict is what makes this safe

The alternative mode defers an untranslatable rule to a runtime filter hook instead — which, on a host that does not wire that hook, means no row restriction at all. data.svc does not wire the runtime filter hook, which is why it runs strict. Lowering the mode without wiring the hook disables row-level security for every rule the translator cannot compile.

Keys that parse but do nothing

Key	Status
rls.related-data.<name>.entity / .filter / .fields	Parses; the only consumer was the runtime filter hook, which is not wired. {{related.X.Y}} references cannot be satisfied.
rowlevelsecurity: at entity level	An alias for the rls block, hoisted into access.rls at load. If both are present, this one wins and silently replaces access.rls.

Tier 3 — fields

fields.read is evaluated once per projected column, with the column name bound as field, and its result is coerced to a bool. Write it as a boolean over field:

access:
  fields:
    read: { language: expr, expression: 'field != "salary" || "hr" in user.roles' }

A denied column fails the whole query rather than dropping the column from the result.

Tier 3 only runs when the request names columns

The projection gate is evaluated over the query’s explicit select list. A read that names no columns — a plain GET /rest/<entity> with no field selection — has an empty select list, so the gate never runs and every column comes back. Tier 3 narrows an explicit projection; it does not restrict a default one. Use compliances: on the field, or a Tier-2 rule, for protection that holds on every read.

fields.write is never enforced, and fields.read is not an allow-list

fields.write parses and is stored on the entity, and no code path reads it. A schema relying on it to stop a caller writing a column has no protection at all.

fields.read written as '"admin" in user.roles ? "all" : ["id","name"]' does not do what it reads like. The string "all" coerces to allow-everything, and the list branch is not a bool — it raises an evaluation error and turns a non-admin read into a 500.

Field masking is not Tier 3

Read-side masking, redaction and hiding are declared per field under compliances:, not under access.fields. The two are separate mechanisms: access.fields decides whether a column may be projected at all, compliances: decides what the value looks like once it is. Field protection documents the directive vocabulary, the mask-pattern grammar, and the pii / phi / pci / gdpr default bundle.

Read-side masking is not wired in data.svc

The hook that applies mask, redact and hidden to scanned rows is not registered in the deployable service, and the compile-side output filter is constructed but never invoked. Compliance directives parse, resolve, and drive the aggregation refusal below and the export and index gates — but a tagged column comes back unmasked on a read that is otherwise allowed.

Until that changes, treat compliances: as classification, not as a read-time control. Keep sensitive columns out of the result with a Tier-2 rule or an explicit projection gate.

Aggregations over tagged columns are refused

COUNT / SUM / AVG / MIN / MAX and the rest are refused over any field carrying encrypted, redact, mask, tokenize, hash, pii, phi, pci, or gdpr, unless the principal passes the entity’s access.actions.unmask rule. COUNT(*), which names no field, is always allowed.

access-lock and final

A product layer may override a service’s access block. access-lock: names the tiers it may not touch, and final: seals the entity outright.

entities:
  - name: audit_event
    access-lock: [rls, actions]   # a product layer may not replace these two tiers
    access:
      actions:
        read: { language: expr, expression: '"auditor" in user.roles' }
      rls:
        read: { language: expr, expression: "row.tenant_id == user.tenant_id" }

  - name: platform_key
    final: true                    # no layer may add fields or touch access at all

Rule	Behaviour
access-lock: values	services | actions | rls | fields; lower-cased at parse, so [RLS, Actions] works. Unknown names are inert.
Tenant-layer access:	Always dropped, locked or not. Only the product layer may override access.
Product override of a locked tier	Dropped.
final: true	No layer contribution of any kind — stronger than locking all four tiers.
A tier the product layer supplies	Replaces the base’s wholesale. There is no per-rule merge.
A tier the product layer omits	Inherited.

Overrides replace, and nothing fails loudly

A product layer supplying actions: with only a read rule wipes the base’s create/update/delete rules — and under deny-by-default those operations then return 403. Omit a tier to inherit it.

Every drop and every override is recorded as a load diagnostic. Nothing is fatal, so a tenant layer’s access: block simply does not exist at runtime and the schema still loads.

Only the tenant layer is folded today

data.svc composes exactly one layer at boot — the tenant overlay, folded as the tenant layer, whose access: block is always dropped. It does not compose a separate product layer over a service base, so access-lock: and final: parse and are honoured by the fold, but nothing in the deployable service currently supplies a layer they would refuse. The rules above are what will apply when it does; the tenant-layer row is the one in force now.

Impersonation

An impersonated request keeps the target user as the principal, with the operator recorded alongside it. Every rule therefore keeps working unchanged — no per-entity rules are needed to support impersonation, and user.id / user.roles are the impersonated user’s.

The read-only impersonation floor does not fire over HTTP

The access gate refuses mutating actions (create, update, delete, purge, restore) for a read-only impersonated credential — but the operator identity is dropped when the principal is rebuilt for the query compiler, so the refusal never triggers on an HTTP request. Do not rely on it to keep a read-only impersonation session from writing; gate mutations with a Tier-1 rule.

Denials and status codes

The HTTP layer classifies by error type first: a denial raised by the runtime hook is a typed access-denied error and maps to 403 whatever its text says. Anything untyped falls through to a substring match, which promotes access denied, not authorised, not authorized and forbidden to 403. The query compiler’s gate and guard return plain errors whose text matches none of those, so they land on the default — 500.

Message	Tier	Status
access denied (tier 0): service "<svc>" not allowed on entity "<entity>"	0	403
access denied (tier 1): entity "<entity>" has no access rule for <op> (deny-by-default); …	1	403
access denied (tier 1): action guard denied <op> on "<entity>"	1	403
access denied (tier 1): action guard denied <purge|restore|unmask|decrypt> on "<entity>"	1	403
access denied (tier 1): action "<action>": entity "<entity>" rule denied <op>	1	403
access denied (tier 2): row denied by RLS create rule on entity <entity>	2	403
access guard eval (<action>): <err>	1	500
accessgate: service "<svc>" not allowed on entity "<entity>" (allowed: […])	0	500
accessgate: action "<action>" on entity "<entity>" denied for principal "<uid>"	1	500
safetyguard: field "<field>" on entity "<entity>" denied for principal "<uid>"	3	500
safetyguard: aggregation <FUNC>(<field>) refused — column carries compliance tags <tags> …	—	500
An untranslatable RLS rule	2	200 with zero rows

The five CRUD handlers carry the codes v2.query_failed, v2.create_failed, v2.update_failed, v2.delete_failed, and v2.restore_failed in the JSON envelope regardless of which tier denied; the status, not the code, tells you it was an authorization failure.

Compile-time denials are also emitted to the audit sink as an access-denied event carrying the action and which gate refused.

Testing a rule

The fastest loop is a local service against PostgreSQL, hitting the anonymous mirror so no token is needed — an anonymous request is an external request, subject to every tier.

curl -s -o /dev/null -w "%{http_code}\n" -H 'X-Customer: dev' -H 'X-Product: dev' -H 'X-Env: dev' -H 'X-Tenant: dev' http://localhost:8099/anon/rest/customer

Situation	Result
No rule for the operation	403, access denied … tier 1
read: { expression: "true" }	200, all rows
A read RLS rule that compiles	200, matching rows only
A read RLS rule that does not compile	200, zero rows
A failing create guard	403, nothing inserted
A failing create RLS rule	403 tier 2, nothing inserted
A rule using script-file:	500
A field rule returning a list	500

Confirm a denial actually stopped the write by checking the row directly, not just the status code.

The other YAML front end

The roles shorthand in the repo’s example schemas does nothing here

A second schema front end — used by bundled examples and the tenant registry — accepts shapes the deployable service’s loader does not, including a direct-action roles form:

# NOT the production grammar. Silently ignored by data.svc.
access:
  create: { roles: [admin] }
  read:   { roles: [admin, owner] }

The production loader accepts only access: {services, actions, rls, fields} and does not reject unknown keys. A schema written in the roles form therefore loads with no action rules at all, and every external operation returns 403 under deny-by-default. There is no roles-list rule form in the shipping engine — express roles as '"admin" in user.roles'.

The same divergence affects two more shapes that appear in internal examples. A bare-string rule (read: "user.id == row.owner_id") is a hard load error — the loader expects a map there and the YAML decode fails. The old inline: key is the quieter one: it is not a rule key the loader knows, so it is dropped without a word, leaving a rule with no body.

Quick reference

Rule keys: language: · expression: · script: · script-file: (does not run) · function: (does not run). Plus rule: at actions: level as an all-slots shorthand.

Languages: expr (default) · cel · js · javascript · lua · starlark · go · wasm.

Bindings: user.id · user.user_id · user.tenant_id · user.tenant · user.roles · user.service · user.session_id · tenant · entity · action · operation · user_id · roles · row.<column> · payload · field (field rules) · extended_action (extended guards).

access:
  services: [ ... ]                                                                    # Tier 0 — breaks HTTP callers
  actions:  { create:, read:, update:, delete:, purge:, restore:, unmask:, decrypt: }  # Tier 1
  rls:                                                                                 # Tier 2
    create:, read:, update:, delete:                                                   #   top-level shortcut keys
    rules: { purge:, restore:, upsert: }                                               #   any operation name
  fields:   { read:, write: }                                                          # Tier 3 — write is not enforced
access-lock: [services, actions, rls, fields]
final: false

Sharp edges:

• Every external-facing operation needs its own Tier-1 rule.
• A rule returning a non-empty string is an allow.
• user.tenant_id is the full customer:product:env:tenant key.
• services: takes an entity off the air over HTTP — there is no service identity to match.
• RLS uses ==, not =; {{ … }} templates do not parse.
• An untranslatable RLS rule returns zero rows with no error.
• RLS purge / restore / upsert need their own keys; they do not inherit delete / update / create.
• fields.read gates only an explicit projection; fields.write does nothing.
• Read-side masking from compliances: is not wired — a tagged column returns unmasked.
• A product layer replaces an access tier wholesale; a tenant layer’s access block is always dropped.

The endpoints these tiers apply to are documented in the Data API HTTP reference; the block overview is at Data API.