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.

Key

A key is a type of authentication secret used for anonymous access to a Fauna database. Unlike tokens, keys are not associated with an identity.

Key collection

Fauna stores keys scoped to a database as documents in the database’s Key system collection.

Key documents have the following FQL structure:

{
  id: "371460335192768546",
  coll: Key,
  ts: Time("2099-07-28T02:23:51.300Z"),
  ttl: Time("2099-07-29T02:23:51.189192Z"),
  secret: "fn...",
  role: "admin"
}
Field name Value type Description

id

Long

A unique identifier assigned by Fauna when the key is created.

coll

Collection

Collection name.

ts

Long

Creation timestamp, with microsecond resolution and time zone.

ttl

Time

Timestamp that defines the key expiration time. When the ttl time expires, the key is deleted.
Default = null. The key persists indefinitely.

secret

String

The secret is a randomly generated cryptographic hash. This field isn’t stored in the document. The secret is only accessible in the Key.create() return. A caller obtains the secret from this return and stores it for subsequent queries. Fauna can’t recover a discarded or lost secret.

role

String

Name of a user-defined role or one of the built-in roles:

  • admin

  • server

  • server-readonly

data

Object

User-defined metadata for the key.

Static methods

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

Method Description

Key.all()

Get the Set of all Key objects.

Key.byId()

Get a key by ID.

Key.create()

Create a key.

Key.firstWhere()

Get the first key matching a predicate function.

Key.toString()

Get the name of the Key collection as a string.

Key.where()

Get keys matching a predicate function.

Instance methods

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

Method Description

key.delete()

Delete a key.

key.exists()

Verify a key.

key.replace()

Replace a key.

key.update()

Update a key.

Dashboard-created keys

The Fauna Dashboard automatically creates a temporary key when you:

  • Log in to the Dashboard. This key has the built-in admin role.

  • Use the Dashboard Shell’s authentication drop-down to run a query using a role other than Admin.

    Run a query as a role

Dashboard-created keys have a 15-minute ttl (time-to-live) and are scoped to their specific database. Related Key documents include a data field with related metadata:

{
  id: "414467050449141793",
  coll: Key,
  ts: Time("2099-11-13T19:17:11.020Z"),
  ttl: Time("2099-11-13T19:32:09.915Z"),
  data: {
    name: "System-generated dashboard key"
  },
  role: "admin"
}

The Dashboard surfaces this metadata in the database’s Keys tab on the Explorer page.

Key’s tab in the Fauna Dashboard

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!