Skip to content

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[ ] [ , callback [ , 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.
callback function() [OPTIONAL] A callback to receive a response. If null, a Promise will be returned
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', ...] [ , callback [,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>

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.