Key Rotation

Rotating your API Key is important for both security reason (when a key is deemed compromizesd) or when seed data changes, i.e. a user decided to change their credentials.

It is important to offer your users ability to rotate old keys into new ones when your users choose to change your app's credentials.

JavaScriptcURL

try {
    const db = await PrefsDB.getkey("my-app", ["current", "key", "seed"]);
    await db.rotate("my-app", ["new", "key", "seed"]);
    // db now holds the new key, with all the data moved over
} catch (error) {
    console.log("Key rotation failed: %s", error.message);
}

# Right after a getkey call for the current key (rotation needs a session from the last 60 seconds):
curl -s -b cookies.txt -c cookies.txt -H "X-Authorization: Token $KEY" \
  -G https://prefsdb.com/api/v1/rotatekey/ \
  --data-urlencode "name=my-app" \
  --data-urlencode "seed=new key seed" \
  --data-urlencode "namespace=$PREFSDB_NAMESPACE"
# {"success":true,"token":"<new key>","message":"Rotation complete. ...",...}

if successful, the old API Key will no longer work. The newly created key must be used from now on.

Key Rotation Atomicity

Key rotation follows principles of atomicity that ensures that the entire operation completes successfully or, if any part of the process fails, the entire transaction is cancelled, and all partial changes are undone.