Secrets store

6 min

The secrets store is your general-purpose storage for sensitive data such as API tokens, private webhook URLs, or account identification. The secrets store is a simplified key value store that allows you to get, put, patch (atomically), or delete data. The data you read/write to the secret store must be a hash of primitive types, such as string, number, boolean, array, or other hash types. Data written to the secrets store is encrypted in-flight and at rest using AES 256-bit encryption.

For more information, see the App SDK documentation.

Caution Do not write sensitive data such as user names, passwords, API keys, or API tokens to any store other than the secrets or settings store.

Manage secrets

To write a secret to the secrets store:

import {storage} from '@zaiusinc/app-sdk';
const siteId = 123;
const token = await authenticate(siteId);
await storage.secrets.put('authToken', {token, siteId});

To get a secret from the secrets store:

const authenticationToken = (await storage.secrets.get('authToken')).token;

To check if a secret exists in the secrets store:

if (await storage.secrets.exists('authToken')) {
  // we already authenticated
}

To update a secret in the secrets store:

const token = await refreshToken(siteId);
// update the token without changing the Site ID
await storage.secrets.patch('authToken', {token});

You can also perform more complicated updates atomically with a callback function:

interface TokenRateLimit {
  counter: number;
  hour: number;
  token: string;
}
await storage.secrets.patch('token', (value) => {
  if (value.hour !== currentHour) {
    value.hour = currentHour;
    value.counter = 0;
  } else {
    value.counter += apiCallCost;
  }
  // return the new value to set based on the previous value
  return value;
});

To delete a secret from the secrets store:

await storage.secrets.delete('authToken');

When users uninstall your app, all secret data is deleted. If users reinstall the app, the secrets store is empty.

Type safety

get, put, and patch are templated methods, so you can specify what type you are providing or expect to be returned for convenient type safety:

interface Token {
  value: string;
  expiration: number;
}
const token = await storage.secrets.get<Token>('token');
if (token.expiration < new Date().getTime() + 60000) {
  // Token is expiring soon!
}