RESTHeart Cloud
Menu

Your users

Permissions

Who may do what in your service, by role: rules with a path, a method and a priority, plus filters that limit a user to their own documents.

A permission says what a role may do: which paths, which methods, and optionally which documents. Every request to your service is checked against them on the server, so the client cannot talk its way past. Permissions are documents in the acl collection, managed under Permissions.

The Permissions page: each rule with its roles

How a request is checked

RESTHeart’s mongoAclAuthorizer evaluates every incoming HTTP request against the ACL documents stored in the acl collection. The authorizer:

  1. Finds all ACL documents whose roles array intersects with the authenticated user’s roles.

  2. Among those, finds documents whose predicate matches the request (path, method, query string, etc.).

  3. Evaluates them in ascending priority order — lower numbers are evaluated first.

  4. If any matching rule permits the request, it is allowed; otherwise it is denied.

The path on Dedicated

Plan ACL collection path

Free / Shared

/acl

Dedicated

/restheart/acl

The UI abstracts this difference — you always navigate to Service → Permissions regardless of plan.

A permission document

{
  "_id": "usersCanReadOrders",
  "roles": ["user"],
  "predicate": "path-prefix('/orders') and method('GET')",
  "priority": 100,
  "mongo": {
    "readFilter": { "owner": "@user._id" },
    "writeFilter": null,
    "mergeRequest": null,
    "projectResponse": null
  }
}
Field Required Description

_id

Yes

Unique identifier for this permission rule. Choose a descriptive name (e.g. readersCanGetPosts).

roles

Yes

Array of role name strings. The rule applies to any authenticated user who holds at least one of these roles. Roles are defined on user documents in the Users section.

predicate

Yes

An Undertow predicate expression that must evaluate to true for the rule to match the incoming request. See Predicate Language below.

priority

Yes

Integer evaluation order. Lower values are evaluated first. Use lower numbers for more specific (higher-priority) rules.

mongo

No

Optional object with MongoDB-level security modifiers. See MongoDB Options below.

apiKeys

No

Only on a permission for /keys: which roles an API key issued under it may carry, and its limits. See API Keys below.

The list

The ACL list is fetched via GET /acl?page=…​&pagesize=…​ and displayed in a paginated, searchable table. Each row shows the _id, the roles, the predicate, the priority, and action buttons.

Search and filter

Use the Search box to apply a MongoDB filter expression, for example:

{ "roles": "user" }

or

{ "priority": { "$lt": 50 } }

A Sort expression (JSON object) can also be applied, mapping to the sort query parameter.

Add a permission

  1. Click New Permission.

  2. Fill in the form fields:

    • ID (_id) — unique name for the rule.

    • Roles — one or more role names this rule applies to.

    • Predicate — the Undertow predicate expression (see below).

    • Priority — integer; lower evaluates first.

    • MongoDB Options — optionally configure readFilter, writeFilter, mergeRequest, and projectResponse.

  3. Click Save. The UI submits POST /acl with the document body.

Edit a permission

  1. Click Edit on a permission row to expand the inline accordion form.

  2. All fields except _id are editable.

  3. Click Save. The UI issues PATCH /acl/<id> with the updated fields.

Delete a permission

Click Delete on a permission row. A confirmation dialog appears before the DELETE /acl/<id> request is issued.

Warning
 Deleting a permission rule takes effect immediately. Any users whose access relied solely on that rule will be denied on the next request.

The predicate language

The predicate field uses the Undertow predicate expression language. A predicate is a boolean expression that is evaluated against the incoming HTTP request. The following predicates are available:

Paths

Predicate Description Example

path('/exact/path')

Matches the exact request path.

path('/status')

path-prefix('/prefix')

Matches any path that starts with the given prefix.

path-prefix('/orders')

path-template('/users/{id}')

Matches parameterised paths; a captured segment is referenced later in the predicate as ${id}.

path-template('/users/{id}/profile')

path-suffix('.json')

Matches paths ending with the given suffix.

path-suffix('.csv')

regex(pattern: '…​', value: %R)

Matches the path against a regular expression.

regex(pattern: '^/data/[0-9]+$', value: %R)

Methods

Predicate Example

method('GET')

method('POST')

method('PUT')

method('DELETE')

method('PATCH')

Combining them

Use and, or, and not to compose complex rules:

path-prefix('/orders') and method('GET')
path-prefix('/reports') and (method('GET') or method('POST'))
path-prefix('/admin') and not method('GET')

Common predicates

Goal Predicate

Allow GET on any path

method('GET')

Allow all methods on /orders and sub-paths

path-prefix('/orders')

Allow POST only to /users

path('/users') and method('POST')

Allow GET and PATCH on /products/{id}

path-template('/products/{id}') and (method('GET') or method('PATCH'))

Allow everything under /public

path-prefix('/public')

Deny DELETE everywhere (use not)

not method('DELETE')

Allow a user to edit only their own document

path-template('/users/{userId}') and method(PATCH) and (equals(@user._id, ${userId}) or equals(@user.sub, ${userId}))

…​ and only one field of it

…​ and bson-request-whitelist(consents)

The @user.sub branch above covers users authenticating with a JWT, where the account id is carried in the sub claim rather than in _id. bson-request-whitelist takes one or more comma-separated keys, dotted for nested ones (bson-request-whitelist(profile.name, profile.surname)), and matches the request body as the client sent it — before any mergeRequest enriches it.

Tip
 Use the Predicate helper tooltip inside the permission form — it shows common predicate patterns inline without leaving the page.

Limit what a user sees and writes

The optional mongo object adds MongoDB-level security on top of the predicate match. These modifiers are applied transparently to every request that matches the rule.

readFilter

A MongoDB filter document appended to every read (GET) query. Clients can only see documents that match the filter, regardless of any filter parameter they provide.

Use case — row-level security:

{
  "mongo": {
    "readFilter": { "owner": "@user._id" }
  }
}

The placeholder @user._id is replaced at runtime with the authenticated user’s _id. This ensures each user sees only documents they own.

writeFilter

A MongoDB filter document applied to every write operation (PUT, PATCH, DELETE). Write operations are silently restricted to documents matching the filter.

Use case — prevent writing to other users' documents:

{
  "mongo": {
    "writeFilter": { "owner": "@user._id" }
  }
}

mergeRequest

A document merged into every write request body before it is persisted. Use this to automatically inject server-enforced fields that clients should not be able to forge.

Use case — auto-stamp ownership on document creation:

{
  "mongo": {
    "mergeRequest": { "owner": "@user._id" }
  }
}

Write sub-documents as nested objects rather than with dotted keys. A merged request that touches both a field and a path inside it is rejected by MongoDB with ConflictingUpdateOperators.

Update operators in mergeRequest

Plain fields are merged into $set. A MongoDB update operator can be merged as well — written with a leading underscore, since the key would otherwise be an illegal one in a stored document. _$push becomes $push when the request is merged.

Use case — append to a server-controlled history, without letting the client overwrite it:

{
  "mongo": {
    "mergeRequest": {
      "lastSeenAt": "@now",
      "_$push": { "auditTrail": { "at": "@now", "by": "@user._id" } }
    }
  }
}

The client sends the field only to satisfy whatever bson-request-whitelist the predicate carries; the value it sends for a key that an array operator manages is discarded, so the two cannot conflict.

projectResponse

A MongoDB projection applied to every response document before it is sent to the client. Use this to mask sensitive fields.

Use case — hide sensitive fields:

{
  "mongo": {
    "projectResponse": { "passwordHash": 0, "internalNotes": 0 }
  }
}

Variables you can use

Variable Value at runtime

@user._id

The _id of the authenticated user.

@user.roles

The roles array of the authenticated user.

@now

The current instant, as a BSON date. Declare it in a JSON Schema as {"_$date": {"type": "number"}}, not as a string.

API keys

A request that authenticates with an API key goes through the same ACL as a password sign-in, with one difference: it carries the key’s roles, not the roles of the user who issued it. A key’s roles are usually narrower than its owner’s, and each one is an ordinary role that you grant permissions to like any other. readFilter, projectResponse and the rest apply as usual.

Which roles a key may be given is decided here too. A permission that lets a role reach /keys carries an apiKeys block:

{
  "_id": "usersIssueKeys",
  "roles": ["user"],
  "predicate": "path-prefix('/keys')",
  "priority": 100,
  "apiKeys": {
    "roles": ["cli-ro"],
    "max-expires-in-days": 90,
    "max-keys-per-user": 5
  }
}
Field Meaning

roles

The roles a key issued under this permission may carry. Required: a non-empty array of distinct role names.

max-expires-in-days

The longest life such a key may have. Optional; the service default applies otherwise, and a user may always ask for less.

max-keys-per-user

How many keys one user may hold at a time. Optional; the service default applies otherwise.

Three things to know:

  • A permission on /keys without the block issues nothing. Its roles reach the endpoint and get a 403 that says so.

  • A malformed block is refused when the permission is written, with a 400 that names the field, whether it comes from the console, rhc or curl.

  • The key’s roles need not be roles the user holds. With the example above a user may issue a cli-ro key, and what that key can do is whatever other permissions grant to cli-ro.

The API Keys page lists the permissions on /keys with the roles each one grants and adds new ones from three fields. They are the same documents you see on the Permissions page.

Priority

Rules with lower priority numbers are evaluated first. This is the opposite of what "priority" means in everyday language — think of it as evaluation order rather than importance.

Priority value Typical use

0

Root / super-admin rules that must always win (e.g. rootCanDoEverything).

1–99

Highly specific rules (exact paths, narrow method sets).

100

Standard application rules.

1000+

Catch-all or fallback rules.
Tip
 When two rules both match a request, the first one evaluated (lowest priority number) takes precedence. Structure your rules so the most specific rules have the lowest numbers.

A worked example: orders

The following three ACL documents implement a typical order-management permission model:

Allow admins to do everything on /orders
{
  "_id": "adminsFullOrders",
  "roles": ["admin"],
  "predicate": "path-prefix('/orders')",
  "priority": 10
}
Allow users to create orders (with auto-stamped owner)
{
  "_id": "usersCreateOrders",
  "roles": ["user"],
  "predicate": "path('/orders') and method('POST')",
  "priority": 100,
  "mongo": {
    "mergeRequest": { "owner": "@user._id" }
  }
}
Allow users to read only their own orders
{
  "_id": "usersReadOwnOrders",
  "roles": ["user"],
  "predicate": "path-prefix('/orders') and method('GET')",
  "priority": 100,
  "mongo": {
    "readFilter": { "owner": "@user._id" }
  }
}

From a script

Operation Endpoint

List permissions

GET /acl?page=…​&pagesize=…​&filter=…​&sort=…​

Create permission

POST /acl

Update permission

PATCH /acl/<id>

Delete permission

DELETE /acl/<id>

On Dedicated plans replace /acl with /restheart/acl in all paths above.

Related pages