Get API Key

---

Although there are certain benefits to having a backend, it is not necessary with PrefsDB.

Still, any operation in PrefsDB will require an API token to read or write data. That key will isolate your (or your user's) data from others.

There are two ways to generate a key:

         PrefsDB.createkey( name, [ seed ] [ , options] )

         PrefsDB.getkey( name, [ seed ] [ , options] )

parameter	type	description
name	text	Display-friendly key identifier
seed	array[]	An array containing a collection of secrets used to generate a unique API Token/Key. The array should contain a combination of secret and salt data elements, but at least one entry should be unique to a user.
options	{ }	[OPTIONAL] An object containing settings and preferences, e.g. email for a new key (See: Options )

All data will be retrievable with the generated key.

Syntax:

    [Promise<PrefsDB> p] = PrefsDB.getkey('key-id', ['secret1', 'secret2', ...] [, options ]);

API Key Session

getkey() also starts a short session that the other calls need. The JavaScript client keeps it and gets a new one by itself when it runs out, so you don't have to do anything. Over plain HTTP, the session is the response's session.token, sent back as an X-Prefs-Session header (see Using the HTTP API directly); it lasts 60 seconds, and calling getkey again gives you a new one.

A brand-new key also needs its email address verified: pass email in the options, and the key works once the link sent to that address is clicked. await db.waitForVerification() resolves when that happens. While testing, an address at sandbox.prefsdb.com skips this step (see Testing without an inbox).

IMPORTANT!

Any change to the seed phrase, even just re-ordering of the items in the seed array, may result in a different key generated and you may loose ability to recover your data should the key be lost. The data itself stays stored (unless it was written with a TTL), but without the key nobody can reach it.

GetKey with a callback

There is a minimal amount of latency involved when generating a key. We should not attempt to use any of the read or write functions until we have fully obtained the API key. PrefsDB.getkey() accepts an onsuccess callback in its options, called with the server's response when the key is ready.

    let apikey = null;

    PrefsDB.getkey('key-id', ['usr', 'pwd', 'val-N'], {
        onsuccess: (response) => {
            apikey = response.token;
            console.log("API Key is: %s", apikey);
        }
    });

GetKey with a Promise

The Promise resolves to a PrefsDB instance, ready to use.

JavaScriptcURL

PrefsDB.getkey('key-id', ['usr', 'pwd', 'val-N'])
    .then((db) => {
        console.log("API Key: %s", db.apitoken());
    });

curl -s -c cookies.txt -G https://prefsdb.com/api/v1/getkey/ \
  --data-urlencode "name=key-id" --data-urlencode "seed=usr pwd val-N" \
  --data-urlencode "namespace=$PREFSDB_NAMESPACE" --data-urlencode "email=you@example.com" \
  -d offline=1

To look up a key generated earlier we can either save it to local variable or do this:

    const token = db.apitoken();

and use it again later with PrefsDB.client(token).

Successful response:

{
  "status"  : "success",
  "success" : true,
  "token"   : "38c26...7cb1",
  "ts"      : "2025-10-29 12:58:52",
  "message" : "New key generated.",
  "originScoped" : true,
  "emailVerificationRequired" : true,
  "sponsored" : false,
  "session" : { "token" : "eyJ0eXAi...", "expiresIn" : 60 }
}

The token is your API key. The response will include a hint whether it is a new or an existing token (message field).

Security concerns

---

Protect the input values from being cached by the browser. Even though one is logged-off, the next person who uses the machine can log-in because the browser autocomplete functionality. To mitigate this, we instruct the input fields not to use any assist features in any way.

Text areas and input fields for PII (name, email, address, phone number) and login credentials (username, password) should be prevented from being stored in the browser.

Use these HTML5 attributes to prevent the browser from storing PII from your form:

<input type="text" spellcheck="false" autocomplete="off" autocorrect="off" autocapitalize="off"></input>

Tip

For security reasons, the API tokens should either always be generated on the fly utilizing secrets not stored anywhere (i.e. credentials from a login form) or should be stored in a secure location like secrets manager utility.

CreateKey vs GetKey

Both methods .createkey() as well as .getkey() perform the same function: generate an API token for you users "account". The difference is in what they do if a key already exists. Which method you decide to use depends on your desired authentication flow in your application.

createkey - if a key already exists , the endpoint will return 403 FORBIDDEN response. It is useful when creating create-account / login-user user authentication pattern.

getkey - if a key already exist, the key will be returned with successful response (200 OK). It is useful when emulating localstorage-like patterns.