Key.create()

Create an key.

Signature

Key.create(data: {*: Any}): <Document>

Description

This method creates a key based on the data parameters. If no database field is supplied, create() is associated and grants access to the current database.

Keys grant anonymous-based access to a database. When create() is called, Fauna returns a document width the key secret field. This field is a password equivalent. The create() caller must retrieve the secret from the result and store it.

At creation is the only time Fauna displays the secret field. The value in this field is equivalent to a password. Fauna cannot recover a secret that is discarded or lost. Copy and save the secret to a password manager or other safe location. Delete and replace keys or tokens for which you have lost the secret. If you no longer need a key or token, you should delete it.

The role field supplied by the create() method configures the key privileges. A key can attach to user-defined roles for attribute-based access control (ABAC) or to the Fauna built-in roles (admin, server, server-readonly).

After the key is created, a caller with the key secret can connect to Fauna and query the associated database for the privileges associated with the key role.

A caller cannot create a key with greater privileges than the key used to make the call.

Parameters

Parameter Type Required Description

data

Object

Object describing the key.

data fields

Name Type Required Description

role

String

Yes

Reference to a role or an Array of roles. Roles can be user-defined roles or the built-in access roles, admin, server, and server-readonly.

database

String

Name of an existing child database. If omitted, the new key grants access to the current database.

priority

Int

A relative weight between 1 and 500 configuring how many resources this key is allowed to utilize. A higher number indicates more resources. By default, this is 1.

data

Object

User-defined metadata to store supplemental key information.

ttl

Time

Timestamp indicating a document lifespan. When the ttl is reached, Fauna removes it. If ttl isn’t set, its default value is null, which causes the document to persist indefinitely or until deleted.

Return value

Type Description

Key

New Key document including the secret value. At creation is the only time Fauna displays the secret field. The value in this field is equivalent to a password. Fauna cannot recover a secret that is discarded or lost.

Examples

Key.create({role: "mgmtTeam", ttl: Time.now().add(1, "day")})
{
  id: "371460335192768546",
  coll: Key,
  ts: Time("2023-07-28T02:23:51.300Z"),
  ttl: Time("2023-07-29T02:23:51.189192Z"),
  secret: "fnAFJ7E071AAIs6Y4zxpfDA_NeMOxJw44V3_ZW_g",
  role: "mgmtTeam"
}

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!