Role document definition

Field name Value type Description


Role name. It can be any string except for events, sets, or self and any string that includes the % percent character.


One or more optional membership configurations. These configurations dynamically define which documents have the privileges. Fauna evaluates this array only for queries that include a Token document. See Membership configuration.


One or more optional privilege configurations. A configuration defines the actions permitted for a resource. The array is a whitelist]. All queries use role privileges to authorize actions. The default privileges is that no actions are permitted. See the Privilege configuration.


Document collection name.


Most recent document update timestamp.


(Optional) Object with metadata fields.

Membership configuration

A membership is an array that dynamically grants the privileges. Each array element specifies a collection resource and an optional predicate.

membership: [{
  resource: "Users",
  predicate: 'user => user.isAdmin'
  resource: "Managers"

The resource is a String referencing a Collection name. All the collection documents make up the role membership. A resource can be any Fauna collection, though typically, it is a user-defined collection of Fauna users. Multiple roles can reference the same resource.

The predicate is an optional field. It specifies a read-only lambda predicate Function. The predicate evaluates the resource document and returns a Boolean value that indicates if the caller querying is allowed the privilege.

For example, Fauna Key collection can be the resource, and the predicate function can evaluate the key name to grant privileges only to key documents with the string report_process in their name.

Privilege configuration

A privileges array configures one or more resource and the actions permitted on that resource.

  privileges: [{
    resource: "Collection",
    actions: {
          delete: false
          create: 'data => "Foo" ==',
          call: '(arg1, arg2) => arg1 == 1 && arg2 == 2'

A resource name is a String type referencing a collection, user-defined function (UDF), or database name. If referencing a collection, the resource can be a user-defined Collection or the name of a native collection. The native collections are the following:

  • AccessProvider

  • Collection

  • Credential

  • Database

  • Function

  • Key

  • Role

  • Token

The actions apply only to the resource and its contents. Actions do not apply to the contents of the contents.

For example, setting resource: Collection grants or denies privileges on all of the user-defined collections but not to the documents in those collections. To grant permissions to documents in a collection, define a collection by name as a resource.

The actions is an Object with one or more key-value pairs. The available actions vary depending on the target resource. The key can be any of the following:

Key Grants Available resources


Create object.

Documents and core schemas, including databases, collections, indexes, functions, and keys.


Delete object.

Documents and core schemas, including databases, collections, indexes, functions, and keys.


Read documents.



Write documents.



A user-defined function (UDFs).

User-defined functions.

Each key takes a value that must be a Boolean or a read-only lambda predicate function that returns a Boolean. A value of true grants the key permission, and false denies it. The predicate must be in long form syntax.

Multiple privileges can be defined on separate roles for a given resource. When a query tries to act on a resource, the action is processed if any privilege grants the action.

Predicate functions execute with read-only server-level permissions, regardless of the access level of the caller. They execute this way because the function needs access to all declared resources to verify privilege.

Each permission key requires distinct function parameters. For example, the write key requires a function with two parameters, while a read function requires one parameter. The following table lists each possible key and the requirements for its corresponding function:

Key Parameter types Description


Object with the new document data.


Object with the new document data.


Reference to the document or a document object to be deleted.


Reference to the document or a document object to be read.


An Object with the original document data and an Object with the new document data to be written.


Parameters to be passed to the user-defined function.

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email

Thank you for your feedback!