Docs Home → Atlas App Services
Device Sync-Compatible Permissions
On this page
When using Device Sync (Flexible Mode), there are special considerations when using the permissions system.
The older Partition-Based Sync uses a completely different permissions system. See Partition-Based Rules and Permissions if you are using Partition-Based Sync.
For a guide to setting up Flexible Sync with common permissions models, see the Device Sync Permissions Guide.
If Device Sync (Flexible Mode) is enabled, an assigned role must be Sync compatible. If the role is not Sync compatible, but its "apply when" evaluated to true, other roles are not considered; access is denied.
A role is not Sync compatible if any of the following conditions are true:
A document filter, insert, or delete expression:
References a field that is not a queryable field
Uses an expansion other than
write, or field-level permissions are not boolean literals (
Field-level permissions are specified for the
When Device Sync is enabled, expressions may only refer to the queryable fields of your data model. If a role refers to any other fields, it becomes Sync incompatible and cannot be used with Device Sync.
Because a Sync-enabled App assigns roles at the start of a Sync session before any specific documents are queried, you can't refer to a document or its field values in an "apply when" expression.
When using Device Sync, some expansions are not supported. The following table specifies which expansions are Sync compatible in either the "apply when" or rule expressions:
Can Use in "Apply When"?
Can Use in Rule Expressions?
Yes with an important consideration
Yes with an important consideration
No. These expansions refer to the document. App Services evaluates "apply when" expressions at session start, so there's no document to evaluate.
No. These expansions might access non-queryable fields of the document, which is not possible.
No. App Services expands the expansions at the start of the session, so the function would not operate on a per-document basis.
App Services causes a client reset if anything about the role changed since the previous session.
At the start of a session, App Services expands all expansions in the "apply
and stores the result. This has the following implications:
If the value changes during a session, App Services continues to use the value as it was at the time of session start.
On the next session, if the value is different from what it was at the start of this session, App Services causes a client reset.
You cannot use the
%functionoperator in read and write rules. Functions would not operate on a per-document basis.
You cannot store permissions information (such as "which document IDs may this user access?") in the user object. Changes would not be re-evaluated until the next user session, and updates would cause a client reset.
If a user's permissions have changed since the last Sync session, Sync triggers a client reset and re-downloads all data with the new permissions applied.
A user's permissions might change in the following situations:
You updated the Data Source configuration to modify the rules.
Your rules reference custom user data to determine permissions dynamically, and the value of that custom user data has changed since the last Sync session.
A client reset will not be triggered in the following cases:
Adding a new collection to an App Services Schema and defining permissions for the new namespace or using default roles. This will not trigger a client reset because permissions have not been applied previously.
Configuring custom permissions for the new collection in the same draft as the new schema. Conversely, deploying a draft with permission changes after you deploy the schema will lead to a client reset, since default permissions were applied in the initial deployment.
Unified Rules System
Prior to February 23, 2023, Device Sync (Flexible Mode) rules existed in the
permissions field of the Sync configuration. These permissions now exist in the same
configuration files as the non-Sync permissions.
When importing an app configured for the older permissions system, App Services automatically migrates the permissions to the new unified rules system. You should not have to migrate apps manually. If you have an old app configuration, you can import and then re-export the migrated configuration.
For reference, the following changes take place in the migration:
default_rule.jsonfile in the data source configuration directory at
Move any collection-specific rules to the
rules.jsonfile in the respective collection configuration directories at
document_filters.write. Ensure both
Add the following to the roles, adjusting for your use case. You can only use
false. Generally, you probably want
document_filterswill restrict read and write access on a per-document level.
"read": true, "write": true, "insert": true, "delete": true, "search": true
This does not apply to apps using Partition-Based Sync. Their permissions configuration remains in the Sync configuration.