create-key

Create a key for the child database.

Syntax

fauna create-key DBNAME [ROLE] [OPTIONS]

Description

The create-key command creates a key to allow access to the child database. When you create the key, you have the option to assign it a role: admin, server, server-readonly, client or a user-defined role name. If you don’t specify a role, it defaults to admin.

If you don’t pass any options at the command line, Fauna uses the default options in the fauna-shell configuration file.

It is not possible to use this command to create a key in a parent or peer database. To access a database outside of the current database, use the Fauna Dashboard.

Arguments

Argument Description

DBNAME

The name of the database you’re creating a key for.

ROLE

Optional key role. One of admin, server, server-readonly, client, or an user-defined role name. Defaults to admin.

Options

Option Description

--domain=<domain>

Optional Fauna server domain, that is, the hostname where Fauna is running. Defaults to db.fauna.com.

--endpoint=<name>

Optional name of the endpoint to use for the command.

--port=<number>

Optional connection port. Defaults to 8443.

--scheme=<scheme>

Optional connection scheme. Must be one of https or http. Defaults to https.

--secret=<secret>

Optional secret to use. A secret authenticates your connection to Fauna, and connects you to a database.

--timeout=<integer>

Optional connection timeout, an integer number of milliseconds. When the interval has elapsed, fauna-shell stops waiting for a response and displays an error.

The default is zero, which means that fauna-shell waits until a response is received.

--graphqlHost=<name>

Not supported.

--graphqlPort=<number>

Not supported.

Example

This example uses a database called my-test-db.

$ fauna list-databases
listing databases
my-test-db

Now, run fauna create-key to create a key for my-test-db. Because a role is not provided, the key role defaults to admin.

$ fauna create-key my-test-db
creating key for database 'my-test-db' with role 'admin'

  created key for database 'my-test-db' with role 'admin'.
  secret: fnAFMpLEJWAAQasGbXhkW5wyvhpOIIkj-j1cmKng

  To access 'my-test-db' with this key, create a client using
  the driver library for your language of choice using
  the above secret.

Now, you can run fauna shell and query for a list of keys, which yields these keys.

$ fauna shell
Connected to https://db.fauna.com
Type Ctrl+D or .exit to exit the shell
> Key.all()
{
  data: [
    {
      id: "374523090163466305",
      coll: Key,
      ts: Time("2023-08-30T21:45:02.040Z"),
      role: "admin"
    }
  ]
}

If you run the Key.byId() to derive a key from a secret, you see that the key derived corresponds to the key in the list above.

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!