Encrypting stored data

The Key-Value Store also lets you store key-value pairs in a secure, encrypted manner. Use the methods listed here to store sensitive data. Data stored through these methods can't be queried through the query method.

To start, import the Forge API package in your app, as follows:

1
2
import { storage } from '@forge/api';

Each installation of your app is subject to the Storage API's quotas and limits. See Storage quotas and Storage limits for more details.

storage.setSecret

Similar to storage.set, storage.setSecret provides a way to store sensitive credentials. Values set with storage.setSecret can only be accessed with storage.getSecret.

The same limitation is applied: persisted JSON values may be up to 128 KiB in size and have a key of up to 500 bytes.

You do not need to identify your app or the active site/installation in your key, as Forge will do this automatically.

Write conflicts are resolved using a last-write-wins strategy.

Method signature

1
2
storage.setSecret(key: string, value: array | boolean | number | object | string ): Promise<void>;

Example

Sets the key example-key to one of the supported value types.

1
2
// array
storage.setSecret('example-key', [ 'Hello', 'World' ]);

// boolean
storage.setSecret('example-key', true);

// number
storage.setSecret('example-key', 123);

// object
storage.setSecret('example-key', { hello: 'world' });

// string
storage.setSecret('example-key', 'Hello world');

storage.getSecret

Gets a value by key, which was stored using storage.setSecret. If the key doesn't exist, the API returns undefined.

Method signature

1
2
storage.getSecret(key: string): Promise<array | boolean | number | object | string>;

Example

Gets the secret value associated with the key example-key.

1
2
// Read the value for key `example-key`
await storage.getSecret('example-key');

storage.deleteSecret

Deletes a secret value by key, this succeeds whether the key exists or not.

Method signature

1
2
storage.deleteSecret(key: string): Promise<void>;

Example

Deletes the value associated with the key example-key, if it hasn't already been deleted.

1
2
// Delete the value with the key `key`
await storage.deleteSecret('example-key');