Introducing RESTHeart's Permission System

When building REST APIs on top of MongoDB, controlling who can access what data is critical. RESTHeart provides a declarative ACL (Access Control List) based authorization system that keeps rules explicit, auditable and easy to reason about.

Introducing RESTHeart's Permission System

Simple yet powerful

A RESTHeart permission is a JSON document (or YAML) that answers three questions:

  1. Who — which roles does this apply to?
  2. What — which resources and operations?
  3. When — under which conditions should access be granted?

Example:

{
  "_id": "userCanReadInventory",
  "roles": ["user"],
  "predicate": "method(GET) and path-prefix('/inventory')",
  "priority": 100
}

This rule allows users with the user role to perform GET requests under /inventory.

Fine-grained MongoDB control

The mongo section lets you narrow access using MongoDB queries and projection. For example:

{
  "roles": ["user"],
  "predicate": "method(GET) and path-prefix('/posts')",
  "mongo": {
    "readFilter": {
      "$or": [
        {"status": "public"},
        {"author": "@user._id"}
      ]
    },
    "projectResponse": {"password": 0, "secret": 0}
  }
}

That configuration returns only public posts or posts authored by the authenticated user and hides sensitive fields automatically.

Dynamic variables and path templates

Permissions support dynamic variables referencing the authenticated user, request properties and path parameters. This enables rules like "a user may access only their own resource":

{
  "predicate": "path-template('/{userid}') and equals(@user._id, ${userid})",
  "mongo": {
    "mergeRequest": {
      "author": "@user._id",
      "createdAt": "@now"
    }
  }
}

Server-side stamping (mergeRequest) enforces ownership and timestamps that clients cannot override.

Flexible storage options

You can store permissions in:

  1. MongoDB (mongoAclAuthorizer) — permissions as documents, manageable via REST
  2. Configuration files (fileAclAuthorizer) — YAML files, suitable for CI/CD and infra-as-code

Both formats use the same schema, so you can mix-and-match according to operational needs.

Common patterns

  • User-owned resources — users can only read/write what they created
  • Multi-tenant isolation — derive tenant id from JWT claims and enforce it automatically
  • Public read, authenticated write — allow anonymous reads while protecting writes
  • Time-based access — enable/disable content based on date/time fields

Resources