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:

         .createkey( keyid, [ seed ] [ , options] ] )

         .getkey( keyid, [ seed ] [ , options] ] )

parameter	type	description
keyid	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 (See: Options )

All data will be retrievable with the generated key.

Syntax:

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

API Key Session

Keys generated via .getkey() method have a short life span. They typically expire if no operation are performed on a key within a minute. If a key expires by the time you are ready to read or write data, simply call .getkey() again.

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. Eventually, all data will then be purged after a period of inactivity.

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. Function .getkey() accepts a callback as one if its parameters - a callback which will be called when key is ready to be used.

    let apikey = null;

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

GetKey with a Promise

    prefs_us.getkey('key-id', ['usr', 'pwd', 'val-N',...])
        .then((response) => response.json())
        .then((data) => { 
            console.log("API Key: %s", data.token); 
        });

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

    const token = prefs_us.apiToken();

Successul response:

{
  status  : "success",
  success : true,
  token   : "38c26...7cb1",
  ts      : "2025-10-29 12:58:52",
  message : "New key generated."
}

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.