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

Learn: Keys

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"),
  role: "admin",
  database: "child_db",
  data: {
    name: "System-generated dashboard key"
  },
  secret: "fn..."
}
Field name Type Read-only Required Description

id

ID

ID for the Key document. The ID is a string-encoded, 64-bit unsigned integer in the 253-1 range. The ID is unique within the collection.

IDs are assigned at document creation. To create a key with a user-provided id using Key.create(), you must use a secret with the create_with_id privilege for the Key collection. If not provided, Fauna generates the id.

coll

Collection

true

Collection name: Key.

ts

Long

true

Last time the document was created or updated.

role

String

true

Role assigned to the key. Can be a user-defined role or one of the following built-in roles:

  • admin

  • server

  • server-readonly

If you specify a user-defined role and a child database, the role must be defined in the specified child database.

database

String | Null

Child database to which the key is scoped. The child database must be directly nested under the database scoped to query’s authentication secret.

If not present, the key is scoped to the same database as the authentication secret.

ttl

Time

Time-to-live (TTL) for the document. Only present if set. If not present or set to null, the document persists indefinitely.

data

{ *: Any } | Null

Arbitrary user-defined metadata for the document.

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.

Static methods

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

Method Description

Key.all()

Get a Set of all keys.

Key.byId()

Get a key by its document id.

Key.create()

Create a key.

Key.firstWhere()

Get the first key that matches a provided predicate.

Key.toString()

Get "Key" as a String.

Key.where()

Get a Set of keys that match a provided predicate.

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()

Test if a key exists.

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!