Skip to content

Getting started

We will rely on what's known as Password Based Encryption concept. You (or your users) provide a "secret", which will then be used to generate and manage API tokens as well as cover all data hashing and encryption needs. The "secret", i.e. like login credentials, never gets sent to the server and never leaves the client side.

So basically, first step is to generate an API key, which will be used to read and write pieces of data. No logins, no sign ups, no accounts - just you and your data that will delete itself when abandoned. Abandonded means there were no reads or writes within designated TTL.

Include prefs.us

First, include prefs.us in your project 

<script src="https://prefs.us/prefs.us.js"></script>

Get API token.

Any read or write operation requires a valid API token (a.k.a. API Key). 

    prefs_us.getkey( keyId , seed [, options])

The function takes two required parameters:

parameter type description
keyId string Token ID or name, a plain string identifying the API token
seed [ ] Seed phrase array, an array of strings containing seed which will be utilized to built the token
options { } /optional/ Additional parameters to override default behavior (i.e. request timeuts etc)

A new API key will be generated if one does not exist.

prefs_us.getkey("keyId", [ "seed1", "seed2",... ], (result)=>{
  console.log("API token: %s", result.token);
});

Once you have a token, you can use .read(), .write(), and post() function to store and retrieve data.

Store data

prefs_us.key("dataKey").write("dataValue");

Store large data blobs

prefs_us.key("dataKey").post("dataBlob");

Read data

prefs_us.key("dataKey").read( (reply)=>{
    let mydata = reply.value
    // do something with your data
});

Quick notes

  1. You may keep and re-use the same key for all subsequent queries to keep your items grouped together, whether saving or retrieving them.

  2. Use grouping parameters such as 'project', 'domain', 'subdomain', or 'list' to help with organizing your data attached to your API key.

  3. Create as many keys as you need but traffic may be a subject to rate limiting.

  4. All timestamps are UTC