Key-Value Store
Custom Entity Store

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.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();

Rate this page: