create-key

Summary

Creates a key for the specified child database.

fauna create-key DBNAME [ROLE]

Description

The create-key command creates a key to allow access to the specified 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 Attribute-based access control (ABAC) 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 specified 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 - The key’s role. One of admin, server, server-readonly, client, or an Attribute-based access control (ABAC) user-defined role name. Defaults to admin.

Options

Option Description

--domain=<domain>

Optional - The Fauna server domain, that is, the hostname where Fauna is running. Defaults to db.fauna.com.
Since the introduction of Region Groups, three cloud domains are available. You do not need to specify a domain, but connections work as expected if you do.
Classic (US and EU): db.fauna.com
United States (US): db.us.fauna.com
Europe (EU): db.eu.fauna.com

--endpoint=<endpoint>

Optional - The name of the endpoint to use for the command.

--port=<port>

Optional - The connection port. Defaults to 8443.

--scheme=<scheme>

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

--secret=<secret>

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

--timeout=<timeout>

Optional - The connection timeout, an integer number of milliseconds. When the specified period 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.

Example

For the purpose of this example, we have created a database called my_test_db.

fauna list-databases
listing databases
my_test_db

Now we run fauna create-key to create a key for my_test_db. Because we are not specifying a role, the key’s 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: fnADr1hqZfACE6CB88ic1TO355X8uhrxx6_ES1VX

  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
Paginate(Keys())
{
  data: [
    Ref(Keys(), "259718958404338186"),
    Ref(Keys(), "259719743570706945"),
    Ref(Keys(), "265437820880945683"),
    Ref(Keys(), "265528117038154259")
  ]
}

If you then run the command to derive a key from a secret, you see that the key derived corresponds to the last key in the list of four keys above and is associated with the database my-test-db.

fauna shell
> KeyFromSecret("fnADr1hqZfACE6CB88ic1TO355X8uhrxx6_ES1VX")
{
  ref: Ref(Keys(), "265528117038154259"),
  ts: 1589486195555000,
  database: Database("my-test-db"),
  role: 'admin',
  hashed_secret: '$2a$05$nyZcKbL6kiUiIyAoAH5TeeqQS2ka5sb4LHAmD2.iQ8G9F5j0ENww2'
}

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!