Keys and built-in roles

The procedures in this tutorial extend the examples created in Get started.

Fauna provides two built-in roles for running queries, admin and server. You can also create database access keys that run with these roles. It is important to understand the privileges granted by each of the built-in roles.

Keys with the admin role can manage their associated database, including the database’s access providers, child databases, documents, user-defined functions (UDFs), indexes, keys, tokens, and user-defined roles.

Keys with the server role are equivalent to the admin role with some exceptions. User-defined roles, child databases, keys, tokens, and their associated documents cannot be directly managed with the server role. Keys with this privilege should be well protected.

In this tutorial, you create database keys with the admin and the server roles. You’ll learn to create keys with the Dashboard and the Fauna Shell.

Query keys

This procedure verifies the setup you did previously by showing you how to query keys from the Shell command line.

  1. Choose Resources to display the Shell.

  2. Select Admin from the run menu.

  3. Query for all keys in your CoffeeStore database.

    Key.all()

    The return should include the coffee-admin document. Except for the return by Key.create(), the secret is never displayed in the document data. If for some reason you do not have the coffee-admin key, create one the prerequisite example for this section.

Create a key with server role

Use the coffee-admin key from the Shell to create another key, this time with the server role.

  1. Choose Secret from the run menu.

  2. Enter the coffee-admin secret in the field provided.

  3. Create a new key named coffee-server that has the built-in server role.

    Key.create({
  role: "server",
  data: {
    name: "coffee-server"
  }
})
    {
  id: "370149530561151010",
  coll: Key,
  ts: Time("2023-07-13T15:09:10.540Z"),
  data: {
    name: "coffee-admin"
  },
  role: "server",
  secret: "fnAFIwkJcuAAIdafadfglWm-fNHMSPKWVvk6orZc3U"
}

    Note that your secret is going to be different. Also, notice that the Key document does not have a default name field. You can add a data.name field if you want to.

  4. Store the secret in a password manager or an equivalent safe location.

  5. Note the id field in the coffee-server key, you are going to use it later.

  6. Choose Secret from the run as menu.

  7. Enter the coffee-server secret in Secret field at the bottom of the page.

  8. Run the Key.all() query with the coffee-server secret which has server level privileges.

    Key.all()
    {
  data: []
}

    The query succeeds but the list is empty. It is empty because the Key collection is one of the native collections a server key has no privileges to manage.

Learn more

These pages can tell you more about the Fauna queries and features used in this page:

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!