CreateKey
CreateKey( param_object )
Description
The CreateKey
function creates a new key, based on the settings in
param_object
, which can be used to access the current database. If you
provide an optional Reference to a child database, the key is
associated with (and provides access to) that database. An admin key
must be used when calling CreateKey
.
Once the key is created, the key’s secret can be used to connect to
Fauna and execute queries within the associated database, with the
permissions associated with the key’s role
.
If you would prefer to use Fauna’s
Attribute-based access control (ABAC), you
should use the Login
function instead.
Parameters
Parameter | Type | Definition and Requirements |
---|---|---|
|
The |
param_object
Field Name | Field Type | Definition and Requirements | ||
---|---|---|---|---|
|
String, Reference to a user-defined role, or an Array of user-defined role references |
The built-in access roles
include |
||
|
Optional - A ref of an existing child database. If not provided, the new key grants access to the current database. |
|||
|
Optional - A relative weight between 1 and 500, inclusive, indicating how many resources this key should be allowed to utilize. Defaults to 1. A higher number means more resources.
|
|||
|
Optional - Contains user-defined metadata for the key. It is provided for the developer to store key-relevant information. |
|||
. |
Optional - A name to apply to the key, to help differentiate this key
from any others that may exist. If provided, this field must exist
within the |
|||
|
Optional - A timestamp that indicates the time-to-live for a document,
which is when the document is removed from the collection and can’t be
queried. The document history can continue to be accessed using
the |
Returns
An object containing the metadata about the results of CreateKey
operations.
Field Name | Field Type | Definition and Requirements |
---|---|---|
|
The Reference is an automatically-generated, unique identifier within the database to the key that was created. |
|
|
The Reference of the database that the key belongs to. |
|
|
The access role for this key. |
|
|
Returned only when provided as a |
|
. |
Returned only when provided as a |
|
|
The timestamp, with microsecond resolution, associated with the creation of the key. |
|
|
The key’s authentication secret. It is only present at creation. You must copy the key’s secret and store it securely for future use. |
|
|
The key’s hashed authentication secret. |
Examples
The following query creates a key for the prydain
database with an
access role of server
:
{
ref: Ref(Keys(), "302043905096942080"),
ts: 1624310364730000,
database: Database("prydain"),
role: 'server',
secret: 'fnAEMRNU1eACAAzEarJdoBSJp5w7-VrGNSXTUMBi',
hashed_secret: '$2a$05$piVqzNsKHfKEFmivgNkhJexOVNaRxfberO1tHj.LqLow9w0ZWygtm'
}
The following query creates a key for the current database with a user-defined role:
{
ref: Ref(Keys(), "302043907216114176"),
ts: 1624310366750000,
role: Role("employees"),
data: { name: 'For employees' },
secret: 'fnAEMRNVVDACAFyp10FYC3DJF1fMsktMFdJBs6WM',
hashed_secret: '$2a$05$wNXwhj6dafxwbXzxG0.LyuPqzOR9Uj4VfSosFPk5/5/u5iP8v6IPG'
}
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!