Key.create()

Create an key.

Signature

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

Description

The Key.create() method creates a Key with the provided data.

A key can’t be create with greater privileges than the key used when calling this method.

If a database isn’t provided, the requested access level is associated with the current database.

The method returns a document that incudes a secret field, which is equivalent to a password and must be copied and stored.

Parameters

Parameter Type Required Description

data

Object

Object describing the key.

data fields

Name Type Required Description

role

String

Yes

Key privilege. A role can be a user-defined role or one of the following built-in roles:

Built-in role Description

admin

Used to manage the associated database, including the database access providers, child databases, documents, functions, indexes, keys, tokens, and user-defined roles. Protect key secrets with administrative privileges in the same way as a root password.

When a user-defined function (UDF) has the admin role, calling that function causes it to be executed with all available privileges.

Reading or writing key documents requires the admin key or equivalent permission.

server

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

The server role has the create, write, and call permissions on User-defined functions (UDFs). The server role can assign any role to a UDF, including the admin role.

server-readonly

Provides read-only access to all data in the database that they’re assigned to. Because they grant unrestricted read access, they should be well protected and only used in trusted or server-side environments.

client

Don’t use.

database

String

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

priority

Int

A relative weight from 1 and 500, inclusive, that configures how many resources this key may utilize. A higher number indicates more resources.
Default = 1

data

Object

User-defined metadata to store supplemental key information.

ttl

Time

Time-to-live timestamp indicating the key lifespan.
Default = null. The key persists indefinitely or until deleted.

Return value

Type Description

Key

Key document that includes the key secret. This is the only time the secret field is displayed. The value in this field is equivalent to a password and can’t be recovered if it is discarded or lost.

Examples

Create a key with a user-defined role and which expires tomorrow:

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!