Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Role

Learn: Roles

We recommend you use FSL to create and update user-defined roles. See FSL role schema.

Fauna uses secrets for authentication and authorization. Roles determine a secret’s privileges, which control data access.

Role collection

Fauna stores user-defined roles as documents in the Role system collection. These documents are an FQL version of the FSL role schema.

Role documents have the following FQL structure:

{
  name: "customer",
  coll: Role,
  ts: Time("2099-07-31T12:37:05.280Z"),
  privileges: [
    {
      resource: "Product",
      actions: {
        read: true
      }
    },
    {
      resource: "Order",
      actions: {
        read: "(ref) => Query.identity() == ref.customer"
      }
    },
    {
      resource: "Customer",
      actions: {
        read: "(ref) => Query.identity() == ref"
      }
    },
    {
      resource: "getOrCreateCart",
      actions: {
        call: "(id) => Query.identity()?.id == id"
      }
    },
    {
      resource: "checkout",
      actions: {
        call: "(name) => true"
      }
    }
  ],
  membership: [
    {
      resource: "Customer"
    },
    {
      resource: "Manager",
      predicate: "(user) => user.accessLevel == \"manager\""
    }
  ],
  data: {
    desc: "End user customer role"
  }
}
Field name Value type Read-only Required Description

name

String

true

Unique name for the role in the database.

Must begin with a letter. Can only include letters, numbers, and underscores. admin, server, and server-readonly are reserved and can’t be used.

coll

Collection

true

Collection name: Role.

ts

Time

true

Last time the document was created or updated.

privileges

Any | Null

Array of privilege objects. Each object allows one or more actions on a resource. See Privilege definition.

membership

Any | Null

Array of membership objects. Each object assigns the role to tokens based on the token’s identity document. See Membership definition.

data

{ *: Any } | Null

Arbitrary user-defined metadata for the document.

Privilege definition

The privileges field accepts an array of privilege objects. Privilege objects have the following schema:

Field name Value type Description

resource

String

Name of a collection or user-defined function (UDF). Supports user-defined collections and the following system collections:

  • AccessProvider

  • Collection

  • Credential

  • Database

  • Function

  • Key

  • Role

  • Token

read privileges grants the ability to call the collection’s indexes.

actions

Object

Types of operations allowed on the resource.

Each key in the object in an action. Privileges support different actions based on the resource type. See Privilege actions.

Each key’s value is true, indicating the role is assigned the privilege unconditionally, or a predicate used to conditionally grant the privilege.

Privilege predicates are passed different arguments based on their action. See Privilege predicate arguments.

Privilege actions

Privileges support different actions based on their resource type.

Resource type Action Allows you to …​

Collection

create

Create documents in the collection. To create documents with a custom id, you must also have the create_with_id privilege.

Collection

delete

Delete documents in the collection.

Collection

read

Read documents in the collection. Can also call the collection’s indexes. To read historical document snapshots, you must also have the history_read privilege.

Collection

write

Update or replace documents in the collection.

Collection

create_with_id

Create documents with a custom id in the collection. You must also have the create privilege.

Collection

history_read

Read snapshots for documents in the collection. See Run a temporal query.

User-defined function (UDF)

call

Call the function.

Privilege predicate arguments

Privilege predicates are passed different arguments based on their action.

Action Predicate function signature

create

(doc: Object) => Boolean | Null

 

doc: Object containing the document to create. Includes metadata fields.

delete

(doc: Object) => Boolean | Null

 

doc: Object containing the document to delete. Includes metadata fields.

read

(doc: Object) => Boolean | Null

 

doc: Object containing the document to read. Includes metadata fields.

write

(oldDoc: Object, newDoc: Object) => Boolean | Null

 

oldDoc: Object containing the original document. Includes metadata fields.

newDoc: Object containing the document to write. Includes metadata fields.

create_with_id

(doc: Object) => Boolean | Null

 

doc: Object containing the document to create. Includes metadata fields.

history_read

(doc: Object) => Boolean | Null

 

doc: Object containing the document to read. Includes metadata fields.

call

(args: Array) => Boolean | Null

 

args: Array containing the function call’s arguments.

Membership definition

The membership field accepts an array of privilege objects. Privilege objects have the following schema:

Field name Value type Description

resource

String

Name of a user-defined collection.

Fauna assigns the role to tokens with an identity document in the collection.

predicate

String

Predicate used to conditionally assign the role. If the predicate is not true, the role is not assigned. If predicate is omitted, the role is assigned unconditionally.

The predicate is passed one argument: an object containing the token’s identity document.

The predicate runs with the built-in server role’s privileges. Supports shorthand syntax.

Static methods

You can use the following static methods to manage the Role collection in FQL.

Method Description

Role.all()

Get a Set of all user-defined roles.

Role.byName()

Get a user-defined role by its name.

Role.create()

Create a user-defined role.

Role.firstWhere()

Get the first user-defined role matching a provided predicate.

Role.toString()

Get "Role" as a String.

Role.where()

Get a Set of user-defined roles that match a provided predicate.

Instance methods

You can use the following instance methods to manage specific Role documents in FQL.

Method Description

role.delete()

Delete a user-defined role.

role.exists()

Test if a user-defined role exists.

role.replace()

Replace a user-defined role.

role.update()

Update a user-defined 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!