FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

User-defined roles

User-defined roles provide configurable, domain-specific security rules. They are the core schema for attribute-based access control.


Roles are created with the CreateRole function, and have the following structure:

Field name Value type Description



The role’s name.

Cannot be events, sets, self, documents, or _. Cannot have the % character.





Optional. One or more membership configuration objects.

User-defined roles can only be managed with an admin key.

Beginning with Fauna 2.11.0, the Fauna access control logic has been changed to use attribute-based access control (ABAC) roles, or the key-based permission system, but never both.

If a resource is a member of an ABAC role, the ABAC role specifies all privileges for that resource. Otherwise, the key-based permission system determines whether read/write/execute privileges are enabled.

For example, when an ABAC role includes a user-defined function as a member, that function cannot be called unless the ABAC privileges permit the call action.

Privilege configuration object

A privilege configuration object defines, for a given resource, what actions are permitted.

Field name Value type Description



A reference to a collection (user-defined or system), index, or user-defined function.

A user-defined collection would be expressed as Collection("<collection_name>").

A system collection would be one of AccessProviders, Collections, Credentials, Databases, Functions, Indexes, Keys, Roles, Tokens.



An object containing key-value pairs, where the keys are action names, and the values are either a boolean value to indicate whether access is permitted, or a predicate function that can compute whether access is permitted.

The available actions are:

  • create: permits the creation of new documents.

  • delete: permits the deletion of existing documents.

  • read: permits the reading of documents, from collections or indexes.

  • write: permits writing to existing documents within a collection.

  • history_read: permits reading historical versions of documents, from collections or indexes.

  • history_write: permits inserting events into the history for an existing document. Required when creating documents with specified document IDs.

  • unrestricted_read: permits the reading of an index without considering any other read permissions.

  • call: permits the calling of user-defined functions.

When configuring read access to an index, both the read and unrestricted_read actions are permitted. The read action grants access to the index’s data. However, an additional read permission check is performed before allowing access to the indexed document, which filters out references that the user cannot read. The unrestricted_read action disables the additional check, returning all of the documents associated with the index.

An action’s value can be a boolean, to indicate whether the action is permitted or not, or a read-only lambda predicate function. Lambda predicate functions must be created using a Query, using the same format that the CreateFunction function accepts. The predicate function takes different parameters depending on the configured action. Predicates must return a boolean value where true grants the action, and false denies it.

Predicate function parameters by action

Action Argument(s) Description



An object containing the new document’s data.



The reference to the document to be deleted.


Reference, or index terms

A reference to the document to be read, or one or more terms to be matched against the target index.


Object, Object, Reference

Three parameters:

  1. An object containing the original document data.

  2. An object containing the new document data (to be written).

  3. A reference to the document to be written.



The reference to the document to be read.


Reference, Timestamp, String, Object

Four parameters:

  1. The reference to the document to be written.

  2. The timestamp to write to, which may create or update an event depending on existence of a matching timestamp.

  3. The action string.

  4. An object containing the new document data.


Index terms

The terms matched against the target index.



The parameters that are to be passed to the user-defined function.

Membership configuration object

A membership configuration object dynamically defines which authenticated resources are members of a given role.

Field name Value type Description



A reference to a collection in which its documents are members of the configured role.


Optional. A read-only lambda predicate function that takes the reference of the authenticated resource and returns a boolean value that indicates whether the referenced resource is a member of the configured role.

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!