Your users
Permissions
Permissions decide what each role may do in your service: which paths, which methods, and which documents, checked on the server for every request.
A permission says what a role may do in your service: which paths, which methods, and optionally which documents. Permissions are documents in the acl collection, managed under Permissions.
Use them to decide who reads and writes what. For example, users with the role user may read /orders, and see only the orders they own.
What you get:
-
Checks on the server. Every request to your service is checked against the permissions on the server, where the client cannot bypass them.
-
Rules per document. Filters can limit a user to their own documents, or hide fields from them.
-
One set of rules for every client. Your app, a script and an AI agent over MCP follow the same permissions.
How a request is checked
Every request is checked against the permissions in the acl collection:
-
Only the permissions for the user’s roles count.
-
They are tried in descending
priorityorder: higher numbers are evaluated first. -
The first one whose
predicatematches the request (path, method, query string and so on) allows it, and itsmongooptions apply. -
If none matches, the request is refused.
The path on Enterprise
| Plan | ACL collection path |
|---|---|
Free, Starter and Pro |
|
Enterprise |
|
In the console the page is always Permissions, whatever the 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 |
|---|---|---|
|
Yes |
A unique name for the permission. Make it say what it does, such as |
|
Yes |
The role names the permission applies to. A user who holds at least one of them is covered. Roles are set on each user, on the Users page. |
|
Yes |
The condition a request must meet for the permission to match. See the predicate language below. |
|
Yes |
The evaluation order. Higher values are evaluated first, so give the more specific permissions the higher numbers. |
|
No |
Filters and changes applied to the data the request reads or writes. See below. |
|
No |
Only on a permission for |
The list
The page lists the permissions with their roles, predicate and priority, a page at a time.
Filter and sort
Type a MongoDB query in the Filter field, for example:
{ "roles": "user" }
or
{ "priority": { "$lt": 50 } }
The Sort field takes a sort document, such as {"priority": -1}.
Add a permission
-
Click Add permission.
-
Fill in the form fields:
-
Permission ID (
_id): a unique name. -
Roles: one or more role names, separated by commas.
-
Predicate: which requests it is about (see below). The console checks it as you type.
-
Priority: higher numbers are evaluated first.
-
MongoDB permissions: optionally, the switches and the JSON of the
mongoblock:readFilter,sort,writeFilter,mergeRequest,projectResponse. See below. -
API key issuance: optionally, the
apiKeysblock of a permission on/keys. See API keys.
-
-
Click Create permission. The console sends
POST /aclwith the document.
Edit a permission
-
Click Edit on a permission. The form opens in place.
-
Change any field except the ID.
-
Click Save. The console sends
PUT /acl/<id>with the whole document.
Delete a permission
Click Delete on a permission and confirm. The console sends DELETE /acl/<id>.
|
Warning
|
A deleted permission stops working within 20 seconds, the time any change to a permission takes to apply. Users whose access relied on it alone are refused from then on. |
The predicate language
A predicate is a condition on the request, written in the Undertow predicate language. These are the ones you will use most:
Paths
| Predicate | Description | Example |
|---|---|---|
|
Matches the exact request path. |
|
|
Matches any path that starts with the given prefix. |
|
|
Matches a path with variable segments. Refer to a captured segment later in the predicate as |
|
|
Matches paths ending with the given suffix. |
|
|
Matches the path against a regular expression. |
|
Methods
| Predicate | Example |
|---|---|
|
|
|
|
|
Combining them
Combine predicates with and, or and not:
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 |
|
Allow all methods on |
|
Allow POST only to |
|
Allow GET and PATCH on |
|
Allow everything under |
|
Allow every method except DELETE, on every path |
|
Allow a user to edit only their own document |
|
… and only one field of it |
|
@user._id is the id of the user making the request, with Basic auth and with a token alike: the tokens a service issues carry _id as a claim.
@qparams['name'] is the query parameter ?name=, as a string, exactly as the client wrote it.
bson-request-whitelist takes one or more comma-separated keys, dotted for nested ones (bson-request-whitelist(profile.name, profile.surname)), and checks the request body as the client sent it, before any mergeRequest adds to it.
|
Tip
|
The Predicate reference panel at the bottom of the Permissions page lists the predicates, and the help icon beside the Predicate field opens this section. |
Limit what a user sees and writes
The optional mongo object acts on the data. It applies to every request the permission allows, and the client does not see it.
readFilter
A MongoDB filter added to every read (GET). The client sees only the documents that match it, whatever filter it sends.
Each user sees only their own documents:
{
"mongo": {
"readFilter": { "owner": "@user._id" }
}
}
@user._id is replaced with the _id of the user making the request, whether the request carries Basic auth or a token.
A condition can depend on the request. With $ifvar it applies only when the client passes a parameter. The client can only restrict the results further:
{
"mongo": {
"readFilter": {
"$and": [
{ "published": true },
{ "$ifvar": ["category", { "category": { "$var": "category" } }] }
]
}
}
}
GET /products?category=desk returns the published desks. Without category the condition is dropped, and only { "published": true } applies.
Keep the mandatory part outside the $ifvar. The variables explain how a parameter is read.
sort
The order of every read the permission allows, as a MongoDB sort document: 1 ascending, -1 descending. Without it, documents come newest first, by _id descending.
{
"mongo": {
"readFilter": { "published": true },
"sort": { "name": 1 }
}
}
When the sort does not end on _id, the server appends it. The same page then returns the same documents every time.
The permission can declare several orders and let the client pick one by name:
{
"mongo": {
"sort": {
"$ifvar": ["order",
{ "by-name": { "name": 1 }, "newest": { "createdAt": -1 } },
{ "createdAt": -1 }
]
}
}
}
?order=by-name sorts by name. Without order the third element applies. A name the permission does not declare gets 400.
To let the client choose only the direction, $var with a default is enough. { "createdAt": { "$var": ["dir", -1] } } sorts newest first, and ?dir=1 oldest first. Any value other than 1 or -1 gets 400.
On a large collection, sort on indexed fields: without an index MongoDB may exceed its in-memory sort limit.
writeFilter
A MongoDB filter applied to every write (PUT, PATCH, DELETE). A write reaches only the documents that match it, and nothing tells the client.
Users cannot change other users' documents:
{
"mongo": {
"writeFilter": { "owner": "@user._id" }
}
}
mergeRequest
A document merged into the body of every write before it is stored. Use it for fields the server sets and the client cannot forge.
A new document is stamped with its owner:
{
"mongo": {
"mergeRequest": { "owner": "@user._id" }
}
}
Write sub-documents as nested objects, without dotted keys. MongoDB rejects a merged request that touches both a field and a path inside it, with ConflictingUpdateOperators.
Update operators in mergeRequest
Plain fields are merged into $set. A MongoDB update operator can be merged too, written with a leading underscore because a key starting with $ cannot be stored in a document. _$push becomes $push when the request is merged.
Append to a history the server controls, which the client cannot overwrite:
{
"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 document in the response. Use it to hide sensitive fields.
Hide sensitive fields:
{
"mongo": {
"projectResponse": { "passwordHash": 0, "internalNotes": 0 }
}
}
allowFilter
Off by default. A read whose request carries filter, sort or sort_by does not match the permission, and gets 403 unless another permission allows it. In the form it is the Free queries switch.
With "allowFilter": true the client may send its own query in a read, within the readFilter. The permission’s sort becomes the default order, used when the client sends no sort.
{
"mongo": {
"allowFilter": true
}
}
We advise against it. It lets the client run any query on the collection the permission covers.
We suggest a query you declare: an aggregation. The app calls it by name, and it reads from the request only the parameters it declares.
For many reads the permission alone is enough:
-
the documents of the caller, or the public ones:
GET /<collection>, withreadFilter, paged withpageandpagesize; -
one document:
GET /<collection>/<id>, with the samereadFilter; -
the count:
GET /<collection>/_size, which counts only the documents of thereadFilter; -
an order, or a criterion among the ones you declare:
sortand$ifvarinreadFilter.
allowFilter covers reads only. A PATCH or DELETE on /<collection>/* needs a filter, and allowBulkPatch and allowBulkDelete decide whether it is allowed.
In a new service, the rootCanDoEverything permission of the root role has allowFilter on.
Variables you can use
| Variable | Value at runtime |
|---|---|
|
The |
|
The |
|
The current instant, as a BSON date. In a JSON Schema, declare it as |
They can also be written { "$var": "@user._id" }.
A query parameter ?x= can be read in two ways:
| Written as | Value at runtime |
|---|---|
|
The parameter read as JSON: |
|
The parameter as a string, exactly as the client wrote it. In predicates and in JSON. |
API keys
A request that authenticates with an API key goes through the same permissions as a password sign-in, with one difference: it carries the key’s roles, which can differ from 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 |
|---|---|
|
The roles a key issued under this permission may carry. Required: a non-empty array of distinct role names. |
|
The longest life such a key may have. Optional; the service default applies otherwise, and a user may always ask for less. |
|
How many keys one user may hold at a time. Optional; the service default applies otherwise. |
Three things to know:
-
A permission on
/keyswithout the block issues nothing. Its roles reach the endpoint and get a403that says so. -
A malformed block is refused when the permission is written, with a
400that names the field, whether it comes from the console,ulabaseorcurl. -
The key’s roles need not be roles the user holds. With the example above a
usermay issue acli-rokey, and what that key can do is whatever other permissions grant tocli-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
Permissions with higher priority numbers are evaluated first. When a user has more than one role, the permissions of all their roles are compared together: among those that match the request, the one with the highest priority applies, together with its mongo options.
Between two matching permissions with the same priority, the one with the higher _id wins, whichever roles they belong to; with generated ids, that is the newer one. Give different priorities to permissions that can match the same request, and the _id never decides.
| Priority value | Typical use |
|---|---|
|
Specific exceptions that must win over a standard permission: an exact path, a single method. |
|
Standard application permissions. |
|
Catch-all or fallback permissions. |
|
|
|
Tip
|
When two permissions of the same role match a request, the one with the higher number decides. Give the most specific ones the highest numbers. |
A worked example: orders
Three permissions for a typical order system:
/orders{
"_id": "adminsFullOrders",
"roles": ["admin"],
"predicate": "path-prefix('/orders')",
"priority": 10
}
{
"_id": "usersCreateOrders",
"roles": ["user"],
"predicate": "path('/orders') and method('POST')",
"priority": 100,
"mongo": {
"mergeRequest": { "owner": "@user._id" }
}
}
{
"_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 |
|
Create permission |
|
Update permission |
|
Delete permission |
|
On Enterprise plans replace /acl with /restheart/acl in all paths above.
Do it from the command line
You can keep your permissions in git and apply them with ulabase setup. The step below writes the third permission of the example above, which lets users read their own orders:
import { defineSetup, step } from '@ulabase/cli';
// users may read orders, and see only those they own
const usersReadOwnOrders = {
roles: ['user'],
predicate: "path-prefix('/orders') and method('GET')",
priority: 100,
mongo: { readFilter: { owner: '@user._id' } },
};
export default defineSetup('Permissions', [
step('usersReadOwnOrders in place', {
async check({ service }) {
if (!(await service.permissionExists('usersReadOwnOrders'))) return false;
// compare the saved permission with the file: if you changed it in git, the apply saves it again
const res = await service.fetch('/acl/usersReadOwnOrders');
const { roles, predicate, priority, mongo } = await res.json();
return JSON.stringify({ roles, predicate, priority, mongo })
=== JSON.stringify(usersReadOwnOrders);
},
apply: ({ service }) => service.putPermission('usersReadOwnOrders', usersReadOwnOrders),
}),
]);
The check compares the stored permission with the one in the file. If you change it in git, the next run writes it again.
Related pages
-
Users: the users and the roles permissions refer to.
-
Guards: rules checked after permissions, on the user’s state.
-
Root user: where the
rootCanDoEverythingpermission comes from. -
Users and permissions through the API: the requests behind this page.
-
API keys: the
apiKeysblock, and what a request made with a key may do. -
Plans: the collection paths that change on Enterprise.