Get API Key

You will need a valid, active API key to perform any operations on prefs.us to read or write data. Any request to read or write data requires first a call to obtain the API key (token) as show below.

         .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. At least one entry should be unique to a user. User supplied login parameters are perfect candidates.
options	{ }	Optional object containing settings and preferences

All data will be retrievable with the generated key. Function .getkey() takes a string which serves as a key identifier plus an array of string values of which are used to build the API key token. The array should contain any combination of secret and public data elements.

    prefs_us.getkey('key-id', ['secret1', 'secret2', ...]);

API Key Expiration

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.

Generate a key callback function.

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);
    });

Generate a token using 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).

HINT: 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.