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.
Simple yet powerful
A RESTHeart permission is a JSON document (or YAML) that answers three questions:
- Who — which roles does this apply to?
- What — which resources and operations?
- 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:
- MongoDB (
mongoAclAuthorizer
) — permissions as documents, manageable via REST - 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
- RESTHeart permissions documentation: restheart.org/docs/security/permissions
- RESTHeart Cloud (try a managed instance): cloud.restheart.com