Storing unencrypted key-value pairs

This page lists the Key-Value Store's basic methods for storing unencrypted data. Data stored through these methods can be queries through the storage.query tool.

To store sensitive data in a more secure manner, you'll need to encrypt your stored data instead. This data, however, can't be queried through the storage.query tool.

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.

The app storage API requires your app to have the storage:app scope. See Add scopes to call an Atlassian REST API guide to add new scopes to your app.

storage.set

Stores a JSON value with a specified key. Forge resolves write conflicts using a last-write-wins strategy.

You can learn more about limits and quotas here.

You don't need to include any identifiers for apps or installations in your key.

Internally, Forge automatically prepends an identifier to every key, mapping it to the right app and installation. This lets you use the full key length without risking conflicts across apps or installations.

Method signature

1
2
storage.set(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.set('example-key', [ 'Hello', 'World' ]);

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

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

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

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

storage.get

Gets a value by key. If the key doesn't exist, the API returns undefined.

Method signature

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

Example

Gets the value associated with the key example-key.

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

storage.delete

Deletes a value by key, this succeeds whether the key exists or not. Write conflicts are resolved using a last-write-wins strategy.

While you can use the storage.delete method to delete app storage when deleting an app, we recommend you raise a ticket with the Atlassian Marketplace team to handle this for you. See Retiring your app for more details.

Method signature

1
2
storage.delete(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.delete('example-key');

storage.bulkSet (EAP)

Bulk operation API is now available as part of Forge Early Access Program (EAP). To start testing this feature, sign up using this form.

Forge’s EAP offers experimental features to selected users for testing and feedback purposes. These features are unsupported and not recommended for use in production environments. They are also subject to change without notice.

For more details, see Forge EAP, Preview, and GA.

Sets multiple key-value pairs in a single operation and returns a type BulkResponse which contains savedKeys and failedKeys.

To start using the bulk operation API (EAP), import the package in your app:

1
2
npm i @forge/api@3.8.1-experimental-1828c63

You can save up to 20 items in a single bulk request and send 45 requests per minute. Each item is subject to Forge’s hosted storage key and object size limits.

Method signature

1
2
storage.bulkSet(items: BulkItem[] ): Promise<BulkResponse>;

// Definition of what needs to be stored
interface BulkItem {
  key: string;
  value: string | number | boolean | Record<string, any> | any[];
}

interface BulkResponse {
  savedKeys: string[];
  failedKeys: string[];
}

Example

Set multiple key-value pairs with keys user1, user2, and user3, and their corresponding values.

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

const results = await storage.bulkSet([{
    key: 'user1'
    value: 'anirudh'
  }, {
    key: 'user2':
    value: 'Sunandan'
  }, {
    key: 'user3':
    value: 'Norman'
  }
]);

storage.query

Builds a query which returns a set of entities matching the provided list of criteria. See Querying data for more information on building and executing queries.

storage.query does not return secret values set by storage.setSecret.

Method signature

1
2
storage.query(): Query

Examples

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

await storage.query()
  // Filter the response to only keys that start with the string 'value'
  .where('key', startsWith('value'))

  // Limit the result size to 10 values
  .limit(10)

  // Use the cursor provided (returned from a previous invocation)
  .cursor('...')

  // Get a list of results
  .getMany();